From eb39a633e8adf3c3cbd5715efeba6ec86115ab11 Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Wed, 16 Dec 2020 15:42:26 +0100
Subject: [PATCH] docs: Improvements suggested by Anders

---
 docs/features/techdocs/concepts.md        | 22 ++++++++++++----------
 docs/features/techdocs/getting-started.md |  5 +++--
 2 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md
index 48204342a9..26254a7e12 100644
--- a/docs/features/techdocs/concepts.md
+++ b/docs/features/techdocs/concepts.md
@@ -8,11 +8,13 @@ Spotify's docs-like-code solution in Backstage
 This page describes concepts that are introduced with Spotify's docs-like-code
 solution in Backstage.
 
+## Generating TechDocs Steps
+
 ### TechDocs Preparer
 
-Prepare is the first step of generating documentation for an entity. It fetches
-the source markdown files from the source code hosting provider (GitHub, GitLab,
-etc.) and passes the files to the generator for next steps.
+Preparing is the first step of generating documentation for an entity. It
+fetches the source markdown files from the source code hosting provider (GitHub,
+GitLab, etc.) and passes the files to the generator for next steps.
 
 There are two kinds of preparers available -
 
@@ -22,13 +24,13 @@ There are two kinds of preparers available -
 
 ### TechDocs Generator
 
-Generation is the second step after preparing the markdown source files. This
+Generating is the second step after preparing the markdown source files. This
 step either runs the TechDocs container (defined below) or runs `mkdocs` CLI to
 generate static HTML files and its assets.
 
 ### TechDocs Publisher
 
-Publish is the third and final step after preparing and generating docs.
+Publishing is the third and final step after preparing and generating docs.
 TechDocs Publisher uploads the generated files to a storage.
 
 The `techdocs-backend` plugin currently comes with two publishers - Google Cloud
@@ -44,7 +46,7 @@ between `techdocs-backend` and the storage)
 
 [TechDocs Backend](https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend)
 
-### TechDocs container
+## TechDocs Container
 
 The TechDocs container is a Docker container available at
 [DockerHub](https://hub.docker.com/r/spotify/techdocs). It builds static HTML
@@ -53,7 +55,7 @@ MkDocs.
 
 [TechDocs Container](https://github.com/backstage/techdocs-container)
 
-### TechDocs Core Plugin
+## TechDocs Core Plugin
 
 The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created
 as a wrapper around multiple MkDocs plugins and Python Markdown extensions to
@@ -61,7 +63,7 @@ standardize the configuration of MkDocs used for TechDocs.
 
 [TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core)
 
-### TechDocs CLI
+## TechDocs CLI
 
 The TechDocs CLI was created to make it easy to write, generate and preview
 documentation for publishing. Currently it mostly acts as a wrapper around the
@@ -70,7 +72,7 @@ container.
 
 [TechDocs CLI](https://github.com/backstage/techdocs-cli)
 
-### TechDocs Reader
+## TechDocs Reader
 
 Documentation generated by TechDocs is generated as static HTML sites. The
 TechDocs Reader was therefore created to be able to integrate pre-generated HTML
@@ -82,7 +84,7 @@ TechDocs widgets for a customized full-featured TechDocs experience.
 
 [TechDocs Reader](https://github.com/backstage/backstage/blob/master/plugins/techdocs/src/reader/README.md)
 
-### Transformers
+## Transformers
 
 Transformers are different pieces of functionality used inside the TechDocs
 Reader. The reason why transformers were introduced was to provide a way to
diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md
index 0437f3ca47..c82bc8b95b 100644
--- a/docs/features/techdocs/getting-started.md
+++ b/docs/features/techdocs/getting-started.md
@@ -12,7 +12,8 @@ If you haven't setup Backstage already, start
 
 > If you used `npx @backstage/create-app`, TechDocs may already be present.
 >
-> You should skip to `Setting the Configuration` below.
+> You should skip to [`Setting the Configuration`](#setting-the-configuration)
+> below.
 
 ## Adding TechDocs frontend plugin
 
@@ -250,7 +251,7 @@ the dependencies. For example, we want `Markdown` version to be
 You can also explicitly install `Markdown==3.2.2` after installing all other
 Python packages.
 
-## Run Backstage locally
+## Running Backstage locally
 
 Start the frontend and the backend app by
 [running backstage locally](../../getting-started/running-backstage-locally.md).