Clarifications to software template documentation (#3070)

* Clarify scaffolders * Tweak preparer * Template clarifications * Minor wording for clarity * Change wording
2020-10-23 17:20:30 -04:00
parent c0eee3a1f6
commit c6c54b1b3a
5 changed files with 30 additions and 26 deletions
@@ -19,7 +19,7 @@ are then harvested and visualized in Backstage.

 ## How it works

-Backstage and the Backstage Service Catalog makes it easy for one team to manage
+Backstage and the Backstage Service Catalog make it easy for one team to manage
 10 services — and makes it possible for your company to manage thousands of
 them.

@@ -5,8 +5,8 @@ description: Documentation on Adding your own Templates
 ---

 Templates are stored in the **Service Catalog** under a kind `Template`. The
-minimum that the template skeleton needs is a `template.yaml` but it would be
-good to also have some files in there that can be templated in.
+minimum that is needed to define a template is a `template.yaml` file, but it
+would be good to also have some files in there that can be templated in.

 A simple `template.yaml` definition might look something like this:

@@ -61,7 +61,7 @@ support to load the location will also need to be added to the Catalog.

 You can add the template files to the catalog through
 [static location configuration](../software-catalog/configuration.md#static-location-configuration),
-for example
+for example:

 ```yaml
 catalog:
@@ -100,11 +100,11 @@ curl \
  --location \
  --request POST 'localhost:7000/api/catalog/locations' \
  --header 'Content-Type: application/json' \
-  --data-raw "{\"type\": \"github\", \"target\": \"https://${YOUR GITHUB REPO}blob/master/${PATH TO FOLDER}/template.yaml\"}"
+  --data-raw "{\"type\": \"github\", \"target\": \"https://${GITHUB URL}/${YOUR GITHUB ORG/REPO}/blob/master/${PATH TO FOLDER}/template.yaml\"}"
 ```

-This should then have added the catalog, and also should now be listed under the
-create page at http://localhost:3000/create.
+This should then have been added the catalog, and be listed under the create
+page at http://localhost:3000/create.

 The `type` field which is chosen in the request to add the `template.yaml` to
 the Service Catalog here, will become the `PreparerKey` which will be used to
@@ -15,10 +15,10 @@ location protocols:
 - `github://`

 These two are added to the `PreparersBuilder` and then passed into the
-`createRouter` function of the `@spotify/plugin-scaffolder-backend`
+`createRouter` function of the `@spotify/plugin-scaffolder-backend`.

-A full example backend can be found
-[here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
+A full example backend can be found in
+[`scaffolder.ts`](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
 but it looks something like the following

 ```ts
@@ -56,7 +56,7 @@ when added to the service catalog. You can see more about this `PreparerKey`
 here in [Register your own template](../adding-templates.md)

 **note:** Currently the catalog supports loading definitions from GitHub + Local
-Files, which translate into the two `PreparerKeys` `file` and `github`. To load
+Files, which translate into the two `PreparerKeys`: `file` and `github`. To load
 from other places, not only will there need to be another preparer, but the
 support to load the location will also need to be added to the Catalog.

@@ -39,17 +39,17 @@ 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), a non-existing github repository name in the format
-`organisation/reponame`, and a GitHub team or user account which should be
+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)

 ### Run!

-Once you've entered values and confirmed, you'll then get a modal with live
+Once you've entered values and confirmed, you'll then get a popup box with live
 progress of what is currently happening with the creation of your template.

 ![Templating Running](../../assets/software-templates/running.png)
@@ -70,6 +70,6 @@ you to the registered component in the catalog:

 ![Catalog](../../assets/software-templates/go-to-catalog.png)

-And then you'll also be able to see it in the Catalog View table
+And then you'll also be able to see it in the Catalog View table:

 ![Catalog](../../assets/software-templates/added-to-the-catalog-list.png)
@@ -211,22 +211,16 @@ docs on creating private GitHub access tokens is available
 Note that the need for private GitHub access tokens will be replaced with GitHub
 Apps integration further down the line.

-#### Github
+#### GitHub

-The Github access token is retrieved from environment variables via the config.
+The GitHub access token is retrieved from environment variables via the config.
 The config file needs to specify what environment variable the token is
 retrieved from. Your config should have the following objects.

 You can configure who can see the new repositories that the scaffolder creates
 by specifying `visibility` option. Valid options are `public`, `private` and
-`internal`. `internal` options is for GitHub Enterprise clients, which means
-public within the organization.
-
-#### Gitlab
-
-For Gitlab, we currently support the configuration of the GitLab publisher and
-allows to configure the private access token and the base URL of a GitLab
-instance:
+`internal`. The `internal` option is for GitHub Enterprise clients, which means
+public within the enterprise.

 ```yaml
 scaffolder:
@@ -234,6 +228,16 @@ scaffolder:
    token:
      $env: GITHUB_TOKEN
    visibility: public # or 'internal' or 'private'
+```
+
+#### GitLab
+
+For GitLab, we currently support the configuration of the GitLab publisher and
+allows to configure the private access token and the base URL of a GitLab
+instance:
+
+```yaml
+scaffolder:
  gitlab:
    api:
      baseUrl: https://gitlab.com