Merge pull request #4312 from adamdmharvey/techdocs-tweaks

docs: Clarifications to TechDocs getting started & other minor updates

docs/features/kubernetes/installation.md

@@ -7,8 +7,8 @@ description: Installing Kubernetes plugin into Backstage
 The Kubernetes feature is a plugin to Backstage, and it is exposed as a tab when
 viewing entities in the software catalog.
 
-If you haven't setup Backstage already, start
-[here](../../getting-started/index.md).
+If you haven't setup Backstage already, read the
+[Getting Started](../../getting-started/index.md).
 
 ## Adding the Kubernetes frontend plugin
 
@@ -111,7 +111,7 @@ Backstage app.
 ## Running Backstage locally
 
 Start the frontend and the backend app by
-[running backstage locally](../../getting-started/running-backstage-locally.md).
+[running Backstage locally](../../getting-started/running-backstage-locally.md).
 
 ## Configuration
 

docs/features/search/README.md

@@ -67,7 +67,7 @@ more to come...
 - As a contributor I should be able to integrate plugin data to the indexing
   process of Backstage Search by using the standardized API.
 - As a software engineer I should be able to search for all content (for
-  example, entities, metadata, documentation) in backstage search.
+  example, entities, metadata, documentation) in Backstage search.
 
 more to come...
 

docs/features/software-templates/extending/create-your-own-templater.md

@@ -86,7 +86,7 @@ follows:
 
 _note_ Currently the templaters that we provide are basically Docker action
 containers that are run on top of the skeleton folder. This keeps dependencies
-to a minimum for running backstage scaffolder, but you don't _have_ to use
+to a minimum for running Backstage scaffolder, but you don't _have_ to use
 Docker. You can `pip install cookiecutter` to run it locally in your backend.
 You could create your own templater that spins up an EC2 instance and downloads
 the folder and does everything using an AMI if you want. It's entirely up to

docs/features/software-templates/index.md

@@ -39,13 +39,13 @@ internally.
 ![Enter some variables](../../assets/software-templates/template-picked.png)
 
 After filling in these variables, you'll get some more fields to fill out which
-are required for backstage usage: the owner (which is a `user` in the backstage
+are required for Backstage usage: the owner (which is a `user` in the backstage
 system), the `storePath` (which right now must be a GitHub Organisation or
 GitHub user and a non-existing GitHub repository name in the format
 `organisation/reponame`), and a GitHub team or user account which should be
 granted admin access to the repository.
 
-![Enter backstage vars](../../assets/software-templates/template-picked-2.png)
+![Enter Backstage vars](../../assets/software-templates/template-picked-2.png)
 
 ### Run!
 

docs/features/techdocs/getting-started.md

@@ -158,7 +158,7 @@ techdocs:
   requestUrl: http://localhost:7000/api/techdocs/
 ```
 
-`requestUrl` is used by TechDocs frontend plugin to discover techdocs-backend
+`requestUrl` is used by TechDocs frontend plugin to discover `techdocs-backend`
 endpoints, and the `storageUrl` is another endpoint in `techdocs-backend` which
 acts as a middleware between TechDocs and the storage (where the static
 generated docs site are stored). These default values should mostly work for
@@ -180,8 +180,8 @@ pipeline, and are being stored in a storage somewhere.
 
 When `techdocs.builder` is set to `'external'`, TechDocs becomes more or less a
 read-only experience where it serves static files from a storage containing all
-the generated documentation. Read more in the "Basic" and "Recommended" setup of
-TechDocs [here](architecture.md)
+the generated documentation. Read more in the "Basic" and "Recommended" sections
+of the [TechDocs Architecture](architecture.md).
 
 ### Choosing storage (publisher)
 
@@ -190,9 +190,9 @@ fetch the sites from. This is managed by a
 [Publisher](./concepts.md#techdocs-publisher). Examples: Google Cloud Storage,
 Amazon S3, or local filesystem of Backstage server.
 
-It is okay to use the local filesystem in a "Basic" setup when you are trying
-out Backstage for the first time. Using Cloud Storage is documented
-[here](./using-cloud-storage.md).
+It is okay to use the local filesystem in a "basic" setup when you are trying
+out Backstage for the first time. At a later time, review
+[Using Cloud Storage](./using-cloud-storage.md).
 
 ```yaml
 techdocs:
@@ -229,23 +229,23 @@ environment is compatible with techdocs.
 You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
 pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
 apt). See our
-[Dockerfile](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
-for the latest requirements. You should be trying to match your Dockerfile with
-this one.
+[`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
+for the latest requirements. You should be trying to match your `Dockerfile`
+with this one.
 
 Note: We recommend Python version 3.7 or higher.
 
-Caveat: Please install the `mkdocs-techdocs-core` package after all other Python
-packages. The order is important to make sure we get correct version of some of
-the dependencies. For example, we want `Markdown` version to be
-[3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
-You can also explicitly install `Markdown==3.2.2` after installing all other
-Python packages.
+> Caveat: Please install the `mkdocs-techdocs-core` package after all other
+> Python packages. The order is important to make sure we get correct version of
+> some of the dependencies. For example, we want `Markdown` version to be
+> [3.2.2](https://github.com/backstage/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11).
+> You can also explicitly install `Markdown==3.2.2` after installing all other
+> Python packages.
 
 ## Running Backstage locally
 
 Start the frontend and the backend app by
-[running backstage locally](../../getting-started/running-backstage-locally.md).
+[running Backstage locally](../../getting-started/running-backstage-locally.md).
 
 Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/)
 to see all your documentation sites.

docs/getting-started/development-environment.md

@@ -31,7 +31,7 @@ $ yarn start
 This should open a local instance of Backstage in your browser, otherwise open
 one of the URLs printed in the terminal.
 
-By default, backstage will start on port 3000, however you can override this by
+By default, Backstage will start on port 3000, however you can override this by
 setting an environment variable `PORT` on your local machine. e.g.
 `export PORT=8080` then running `yarn start`. Or `PORT=8080 yarn start`.
 

docs/plugins/create-a-plugin.md

@@ -9,8 +9,9 @@ A Backstage Plugin adds functionality to Backstage.
 ## Create a Plugin
 
 To create a new plugin, make sure you've run `yarn install` and installed
-dependencies, then run the following on your command line (invoking the
-`backstage-cli`).
+dependencies, then run the following on your command line (a shortcut to
+invoking the [`backstage-cli create-plugin`](../cli/commands.md#create-plugin))
+from the root of your project.
 
 ```bash
 yarn create-plugin

docs/plugins/integrating-plugin-into-service-catalog.md

@@ -59,7 +59,7 @@ accordingly inside `Router.tsx`)
 ### Import and use router in the APP
 
 In the `app/src/components/catalog/EntityPage.tsx` (app === your folder,
-containing backstage app) import your created Router:
+containing Backstage app) import your created Router:
 
 ```tsx
 import { Router as MyPluginRouter } from '@backstage/plugin-my-plugin;

docs/reference/utility-apis/BackstageIdentityApi.md

@@ -79,7 +79,7 @@ Referenced by: [getBackstageIdentity](#getbackstageidentity).
 <pre>
 export type BackstageIdentity = {
   /**
-   * The backstage user ID.
+   * The Backstage user ID.
    */
   id: string;