[Techdocs] Improve create publish docs (#7626)

2021-10-18 18:19:38 +02:00
parent 931ca66867
commit 405dbc80e7
2 changed files with 111 additions and 19 deletions
@@ -5,11 +5,12 @@ sidebar_label: Creating and Publishing Documentation
 description: Guidance on how to create and publish documentation
 ---

-This section will guide you through:
+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)
-  - [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository)
+  - [Enable documentation for an already existing entity](#enable-documentation-for-an-already-existing-entity)
 - [Writing and previewing your documentation](#writing-and-previewing-your-documentation)

 ## Prerequisites
@@ -21,29 +22,47 @@ This section will guide you through:

 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.
+[Enable documentation for an already existing entity setup](#enable-documentation-for-an-already-existing-entity)
+section below. Otherwise, continue reading to create a new software entity
+including documentation from scratch.
+
+### Use any software template
+
+TechDocs is built on top of the
+[docs like code approach](https://www.docslikecode.com/about/). This, in short,
+means that you should keep documentation close to the code.
+
+Your Backstage app has a set of software templates added by default. All of
+these software templates include everything you need to get your TechDocs site
+up and running and to start writing your documentation.
+
+If you have created software templates that do not include documentation by
+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-documentation-setup-to-your-software-templates)
+to get started.

 ### Use the documentation template

-Your working Backstage instance should by default have a documentation template
-added. If not, copy the catalog locations from the
+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 as below mentioned in manual
-documentation setup, and is otherwise empty.
+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.

-### Manually add documentation setup to already existing repository
+### Enable documentation for an already existing entity

 Prerequisites:

- An existing component
+- An existing entity
  [registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog)
  (e.g. via a `catalog-info.yaml` file).

@@ -72,11 +91,11 @@ metadata:
 The
 [`backstage.io/techdocs-ref` annotation](../software-catalog/well-known-annotations.md#backstageiotechdocs-ref)
 is used by TechDocs to download the documentation source files for generating an
-Entity's TechDocs site.
+entity's TechDocs site.

-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.)_
+Create a `/docs` folder in the root of your repository with at least an
+`index.md` file in it. _(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.)_

 > Note - Although `docs` is a popular directory name for storing documentation,
 > it can be renamed to something else and can be configured by `mkdocs.yml`. See
@@ -95,9 +114,10 @@ updated documentation next time you run Backstage!

 ## Writing and previewing your documentation

-Using the `techdocs-cli` you can preview your docs inside a local Backstage
-instance and get live reload on changes. This is useful when you want to preview
-your documentation while writing.
+Using the [techdocs-cli](https://github.com/backstage/techdocs-cli) you can
+preview your docs inside a local Backstage instance and get live reload on
+changes. This is useful when you want to preview your documentation while
+writing.

 To do this you can run:

@@ -348,3 +348,75 @@ const app = createApp({
  ],
 });
 ```
+
+## How to add the documentation setup to your software templates
+
+[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index)
+in Backstage is a tool that can help your users to create new components out of
+already configured templates. It comes with a set of default templates to use,
+but you can also
+[add your own templates](https://backstage.io/docs/features/software-templates/adding-templates).
+
+If you have your own templates set up, we highly recommend that you include the
+required setup for TechDocs in those templates. When creating a new component,
+your users will then get a TechDocs site up and running automatically, ready for
+them to start writing technical documentation.
+
+The purpose of this how-to guide is to walk you through how to add the required
+configuration and some default markdown files to your new template. You can use
+the
+[react-ssr-template](https://github.com/backstage/software-templates/tree/main/scaffolder-templates/react-ssr-template)
+as a reference when walking through the steps.
+
+Prerequisites:
+
+- An existing software template including a `template.yaml` together with a
+  skeleton folder including at least a `catalog-info.yaml`.
+
+1. Update your component's entity description by adding the following lines to
+   the `catalog-info.yaml` in your skeleton folder.
+
+```yaml
+annotations:
+  backstage.io/techdocs-ref: dir:.
+```
+
+The
+[`backstage.io/techdocs-ref` annotation](../software-catalog/well-known-annotations.md#backstageiotechdocs-ref)
+is used by TechDocs to download the documentation source files for generating an
+entity's TechDocs site.
+
+2. Create an `mkdocs.yml` file in the root of your skeleton folder with the
+   following content:
+
+```yaml
+site_name: ${{values.component_id}}
+site_description: ${{values.description}}
+
+nav:
+  - Introduction: index.md
+
+plugins:
+  - techdocs-core
+```
+
+3. Create a `/docs` folder in the skeleton folder with at least an `index.md`
+   file in it.
+
+The `docs/index.md` can for example have the following content:
+
+```md
+# ${{ values.component_id }}
+
+${{ values.description }}
+
+## Getting started
+
+Start writing your documentation by adding more markdown (.md) files to this
+folder (/docs) or replace the content in this file.
+```
+
+> Note: The values of `site_name`, `component_id` and `site_description` depends
+> on how you have configured your `template.yaml`
+
+Done! You now have support for TechDocs in your own software template!