diff --git a/docs/assets/architecture-decisions/catalog-core-entities.png b/docs/assets/architecture-decisions/catalog-core-entities.png
index b7f238708f..26099839ef 100644
Binary files a/docs/assets/architecture-decisions/catalog-core-entities.png and b/docs/assets/architecture-decisions/catalog-core-entities.png differ
diff --git a/docs/features/software-catalog/configuration.md b/docs/features/software-catalog/configuration.md
index d5ad240dde..3ffd01a38a 100644
--- a/docs/features/software-catalog/configuration.md
+++ b/docs/features/software-catalog/configuration.md
@@ -6,17 +6,17 @@ description: Documentation on Software Catalog Configuration
 
 ## Processors
 
-The catalog makes use of so called processors to perform all kinds of ingestion
-tasks, such as reading raw entity data from a remote source, parsing it,
-transforming it, and validating it. These processors are configured under the
-`catalog.processors` key.
+The catalog has a concept of _processors_ to perform catalog ingestion tasks,
+such as reading raw entity data from a remote source, parsing it, transforming
+it, and validating it. These processors are configured under the
+`catalog.processors` configuration key.
 
 ### Processor: url
 
 The `url` processor is responsible for fetching entity data from files in any
-external provider like GitHub, GitLab, Bitbucket, etc. The configuration of this
-processor lives under the top-level `integrations` key, as it is used by other
-parts of Backstage too.
+external provider like GitHub, GitLab, Bitbucket, etc. Unlike other processors,
+the configuration of this processor lives under the top-level `integrations`
+key, as it is used by other parts of Backstage too.
 
 ```yaml
 integrations:
diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md
index 17eaf80832..e4b046d76f 100644
--- a/docs/features/software-catalog/descriptor-format.md
+++ b/docs/features/software-catalog/descriptor-format.md
@@ -35,8 +35,32 @@ we recommend that you name them `catalog-info.yaml`.
 
 ## Overall Shape Of An Entity
 
-The following is an example of the shape of an entity as returned from the
-software catalog API.
+The following is an example of a descriptor file for a Component entity:
+
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: artist-web
+  description: The place to be, for great artists
+  labels:
+    system: public-websites
+  annotations:
+    example.com/service-discovery: artistweb
+    circleci.com/project-slug: github/example-org/artist-website
+  tags:
+    - java
+  links:
+    - url: https://admin.example-org.com
+      title: Admin Dashboard
+      icon: dashboard
+spec:
+  type: website
+  lifecycle: production
+  owner: artist-relations-team
+```
+
+This is the same entity as returned in JSON from the software catalog API:
 
 ```js
 {
@@ -71,31 +95,6 @@ software catalog API.
 }
 ```
 
-The corresponding descriptor file that generated it may look as follows:
-
-```yaml
-apiVersion: backstage.io/v1alpha1
-kind: Component
-metadata:
-  name: artist-web
-  description: The place to be, for great artists
-  labels:
-    system: public-websites
-  annotations:
-    example.com/service-discovery: artistweb
-    circleci.com/project-slug: github/example-org/artist-website
-  tags:
-    - java
-  links:
-    - url: https://admin.example-org.com
-      title: Admin Dashboard
-      icon: dashboard
-spec:
-  type: website
-  lifecycle: production
-  owner: artist-relations-team
-```
-
 The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the
 _envelope_, defining the overall structure of all kinds of entity. Likewise,
 some metadata fields like `name`, `labels`, and `annotations` are of special
diff --git a/docs/features/software-catalog/installation.md b/docs/features/software-catalog/installation.md
index ae8c671ed1..19b4c73900 100644
--- a/docs/features/software-catalog/installation.md
+++ b/docs/features/software-catalog/installation.md
@@ -10,8 +10,9 @@ outlined below.
 
 ## Installing @backstage/plugin-catalog
 
-> **Note that if you used `npx @backstage/create-app`, the plugin may already be
-> present**
+> **Note that if you used `npx @backstage/create-app`, the plugin is already
+> installed and you can skip to
+> [adding entries to the catalog](#adding-entries-to-the-catalog)**
 
 The catalog frontend plugin should be installed in your `app` package, which is
 created as a part of `@backstage/create-app`. To install the package, run:
@@ -21,10 +22,6 @@ cd packages/app
 yarn add @backstage/plugin-catalog
 ```
 
-Make sure the version of `@backstage/plugin-catalog` matches the version of
-other `@backstage` packages. You can update it in `packages/app/package.json` if
-it doesn't.
-
 ### Adding the Plugin to your `packages/app`
 
 Add the following entry to the head of your `packages/app/src/plugins.ts`:
@@ -37,6 +34,7 @@ Next we need to install the two pages that the catalog plugin provides. You can
 choose any name for these routes, but we recommend the following:
 
 ```tsx
+// packages/app/src/App.tsx
 import {
   catalogPlugin,
   CatalogIndexPage,
@@ -60,6 +58,7 @@ user can create components. In a typical setup the create component route will
 be linked to the Scaffolder plugin's template index page:
 
 ```ts
+// packages/app/src/App.tsx
 import { catalogPlugin } from '@backstage/plugin-catalog';
 import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
 
@@ -76,6 +75,7 @@ const app = createApp({
 You may also want to add a link to the catalog index page to your sidebar:
 
 ```tsx
+// packages/app/src/sidebar.tsx
 import HomeIcon from '@material-ui/icons/Home';
 
 // Somewhere within the <Sidebar>
@@ -88,7 +88,7 @@ This is all that is needed for the frontend part of the Catalog plugin to work!
 
 Since the catalog plugin currently ships with a sentry plugin `InfoCard`
 installed by default, you'll need to set `sentry.organization` in your
-`app-yaml.yaml`. For example:
+`app-config.yaml`. For example:
 
 ```yaml
 sentry:
@@ -101,8 +101,9 @@ as that will conflict with the catalog routes.
 
 ## Installing @backstage/plugin-catalog-backend
 
-> **Note that if you used `npx @backstage/create-app`, the plugin may already be
-> present**
+> **Note that if you used `npx @backstage/create-app`, the plugin is already
+> installed and you can skip to
+> [adding entries to the catalog](#adding-entries-to-the-catalog)**
 
 The catalog backend should be installed in your `backend` package, which is
 created as a part of `@backstage/create-app`. To install the package, run:
@@ -112,59 +113,12 @@ cd packages/backend
 yarn add @backstage/plugin-catalog-backend
 ```
 
-Make sure the version of `@backstage/plugin-catalog-backend` matches the version
-of other `@backstage` packages. You can update it in
-`packages/backend/package.json` if it doesn't.
-
 ### Adding the Plugin to your `packages/backend`
 
 You'll need to add the plugin to the `backend`'s router. You can do this by
-creating a file called `packages/backend/src/plugins/catalog.ts` with the
-following contents to get you up and running quickly.
-
-```ts
-import {
-  createRouter,
-  DatabaseEntitiesCatalog,
-  DatabaseLocationsCatalog,
-  DatabaseManager,
-  HigherOrderOperations,
-  LocationReaders,
-  runPeriodically,
-} from '@backstage/plugin-catalog-backend';
-import { PluginEnvironment } from '../types';
-import { useHotCleanup } from '@backstage/backend-common';
-
-export default async function createPlugin({
-  logger,
-  database,
-}: PluginEnvironment) {
-  const locationReader = new LocationReaders(logger);
-
-  const db = await DatabaseManager.createDatabase(database, { logger });
-  const entitiesCatalog = new DatabaseEntitiesCatalog(db);
-  const locationsCatalog = new DatabaseLocationsCatalog(db);
-  const higherOrderOperation = new HigherOrderOperations(
-    entitiesCatalog,
-    locationsCatalog,
-    locationReader,
-    db,
-    logger,
-  );
-
-  useHotCleanup(
-    module,
-    runPeriodically(() => higherOrderOperation.refreshAllLocations(), 10000),
-  );
-
-  return await createRouter({
-    entitiesCatalog,
-    locationsCatalog,
-    higherOrderOperation,
-    logger,
-  });
-}
-```
+creating a file called `packages/backend/src/plugins/catalog.ts` with contents
+matching
+[catalog.ts in the create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts).
 
 Once the `catalog.ts` router setup file is in place, add the router to
 `packages/backend/src/index.ts`:
@@ -174,10 +128,9 @@ import catalog from './plugins/catalog';
 
 const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
 
-const service = createServiceBuilder(module)
-  .loadConfig(configReader)
-  /** several different routers */
-  .addRouter('/catalog', await catalog(catalogEnv));
+const apiRouter = Router();
+/** several different routers */
+apiRouter.use('/catalog', await catalog(catalogEnv));
 ```
 
 ### Adding Entries to the Catalog
@@ -192,7 +145,7 @@ our example templates through static configuration. Add the following to the
 ```yaml
 catalog:
   locations:
-    # Backstage Example Component
+    # Backstage Example Components
     - type: url
       target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
     - type: url
@@ -217,8 +170,9 @@ Finally, start up the backend with the new configuration:
 
 ```bash
 cd packages/backend
+# or `yarn dev` to run both frontend and backend
 yarn start
 ```
 
-If you've also set up the frontend plugin, so you should be ready to go browse
-the catalog at [localhost:3000](http://localhost:3000) now!
+If you've also set up the frontend plugin, you should be ready to go browse the
+catalog at [localhost:3000](http://localhost:3000) now!
diff --git a/docs/features/software-catalog/system-model.md b/docs/features/software-catalog/system-model.md
index f0ead20664..eedb94d02e 100644
--- a/docs/features/software-catalog/system-model.md
+++ b/docs/features/software-catalog/system-model.md
@@ -108,8 +108,3 @@ domain would come with some documentation on how to accept payments for a new
 product or use-case, share the same entity types in their APIs, and integrate
 well with each other. Other domains could be “Content Ingestion”, “Ads” or
 “Search”.
-
-## Links
-
-- [Original RFC](https://github.com/backstage/backstage/issues/390)
-- [YAML file format](../../architecture-decisions/adr002-default-catalog-file-format.md)
diff --git a/docs/features/software-templates/installation.md b/docs/features/software-templates/installation.md
index fd51bffa5b..baaa45a26d 100644
--- a/docs/features/software-templates/installation.md
+++ b/docs/features/software-templates/installation.md
@@ -24,10 +24,6 @@ cd packages/app
 yarn add @backstage/plugin-scaffolder
 ```
 
-Make sure the version of `@backstage/plugin-scaffolder` matches the version of
-other `@backstage` packages. You can update it in `packages/app/package.json` if
-it doesn't.
-
 ### Adding the Plugin to your `packages/app`
 
 Add the following entry to the head of your `packages/app/src/plugins.ts`:
@@ -71,10 +67,6 @@ cd packages/backend
 yarn add @backstage/plugin-scaffolder-backend
 ```
 
-Make sure the version of `@backstage/plugin-scaffolder-backend` matches the
-version of other `@backstage` packages. You can update it in
-`packages/backend/package.json` if it doesn't.
-
 ### Adding the Plugin to your `packages/backend`
 
 You'll need to add the plugin to the `backend`'s router. You can do this by
diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md
index d9dbb67ab2..4b88e78db3 100644
--- a/docs/features/software-templates/writing-templates.md
+++ b/docs/features/software-templates/writing-templates.md
@@ -265,7 +265,7 @@ The main two that are used are the following:
 ```yaml
 output:
   remoteUrl: '{{ steps.publish.output.remoteUrl }}' # link to the remote repository
-  entityRef: '{{ steps.register.output.entityRef }}' # link to the entitiy that has been ingested to the catalog
+  entityRef: '{{ steps.register.output.entityRef }}' # link to the entity that has been ingested to the catalog
 ```
 
 ### The templating syntax