Merge pull request #21788 from chlab/patch-1

Describe how to add standalone techdocs

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

@@ -9,8 +9,8 @@ This section will guide you through how to:
 
 - [Create a basic documentation setup](#create-a-basic-documentation-setup)
   - [Use any software template](#use-any-software-template)
-  - [Use the documentation template](#use-the-documentation-template)
   - [Enable documentation for an already existing entity](#enable-documentation-for-an-already-existing-entity)
+  - [Create a standalone documentation](#create-a-standalone-documentation)
 - [Writing and previewing your documentation](#writing-and-previewing-your-documentation)
 
 ## Prerequisites
@@ -41,23 +41,6 @@ default, we highly recommend you to set that up. Follow our how-to guide
 [How to add documentation setup to your software templates](./how-to-guides.md#how-to-add-the-documentation-setup-to-your-software-templates)
 to get started.
 
-### Use the documentation template
-
-There could be _some_ situations where you don't want to keep your docs close to
-your code, but still want to publish documentation - for example, an onboarding
-tutorial. For this use case, we have put together a documentation template. Your
-Backstage instance should by default have a documentation template added. If
-not, copy the catalog locations from the
-[create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs)
-to add the documentation template. The template creates a component with
-**only** TechDocs configuration and default markdown files, and is otherwise
-empty.
-
-![Documentation Template](../../assets/techdocs/documentation-template.png)
-
-Create an entity from the documentation template and you will get the needed
-setup for free.
-
 ### Enable documentation for an already existing entity
 
 Prerequisites:
@@ -115,6 +98,56 @@ This is a basic example of documentation.
 Commit your changes, open a pull request and merge. You will now get your
 updated documentation next time you run Backstage!
 
+### Create a standalone documentation
+
+There could be _some_ situations where you don't want to keep your docs close to
+your code, but still want to publish documentation - for example, an onboarding
+tutorial. For this case, you can create a documentation component, which will be
+published as a standalone part of TechDocs.
+
+First, create an entity for your documentation. A minimal example could look like
+this:
+
+```yaml title="catalog-info.yaml"
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: a-unique-name-for-your-docs
+  annotations:
+    # this could also be `url:<url>` if the documentation isn't in the same location
+    backstage.io/techdocs-ref: dir:.
+spec:
+  type: documentation
+  lifecycle: experimental
+  owner: user-or-team-name
+```
+
+Next, create the config file for [mkdocs](https://www.mkdocs.org/), which will be
+used to parse your docs:
+
+```yaml title="mkdocs.yml"
+site_name: a-unique-name-for-your-docs
+site_description: An informative description
+plugins:
+  - techdocs-core
+nav:
+  - Getting Started: index.md
+```
+
+Finally, add your index.md Markdown file, in a folder named `docs/` with your desired
+documentation in Markdown. Your file structure should now look like this:
+
+```
+your-great-documentation/
+  docs/
+    index.md
+  catalog-info.yaml
+  mkdocs.yml
+```
+
+Last but not least, register your component in the software catalog using
+[one of several options](../software-catalog/index.md#adding-components-to-the-catalog).
+
 ## Writing and previewing your documentation
 
 Using the [techdocs-cli](https://github.com/backstage/backstage/tree/master/packages/techdocs-cli) you can