Clarify catalog info YAML, TechDocs (#2882)

* Add note about catalog-info.yaml convention to format docs.

* Improve TechDocs Create & Publish Docs:
- Clarify the two paths to getting started
- Clarify `catalog-info.yaml` / component registration
- Minor grammar cleanup

* Correct link to software catalog overview

docs/features/software-catalog/descriptor-format.md

@@ -14,6 +14,9 @@ natively. In the API request/response cycle, a JSON representation is used,
 while the descriptor files are on YAML format to be more easily maintainable by
 humans. However, the structure and semantics is the same in both cases.
 
+Although it's possible to name catalog entity descriptor files however you wish,
+we recommend that you name them `catalog-info.yaml`.
+
 ## Contents
 
 - [Overall Shape Of An Entity](#overall-shape-of-an-entity)

docs/features/techdocs/creating-and-publishing.md

@@ -19,6 +19,12 @@ This section will guide you through:
 
 ## Create a basic documentation setup
 
+If you have an existing repository that you'd like to add documentation to, skip
+to the
+[Manually add documentation setup](#manually-add-documentation-setup-to-already-existing-repository)
+section below. Otherwise, continue reading to start a documentation repo from
+scratch.
+
 ### Use the documentation template
 
 Your working Backstage instance should by default have a documentation template
@@ -35,9 +41,11 @@ setup for free.
 
 Prerequisities:
 
-- `catalog-info.yml` file registered to Backstage.
+- An existing component
+  [registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog)
+  (e.g. via a `catalog-info.yaml` file).
 
-Create a `mkdocs.yml` file in the root of the repository with the following
+Create an `mkdocs.yml` file in the root of your repository with the following
 content:
 
 ```yaml
@@ -50,8 +58,8 @@ plugins:
   - techdocs-core
 ```
 
-Update your `catalog-info.yaml` file in the root of the repository with the
-following content:
+Update your component's entity description by adding the following lines to its
+`catalog-info.yaml` in the root of its repository:
 
 ```yaml
 metadata:
@@ -59,7 +67,7 @@ metadata:
     backstage.io/techdocs-ref: dir:./
 ```
 
-Create a `/docs` folder in the root of the project with at least a `index.md`
+Create a `/docs` folder in the root of the project with at least an `index.md`
 file. _(If you add more markdown files, make sure to update the nav in the
 mkdocs.yml file to get a proper navigation for your documentation.)_