Merge pull request #1713 from spotify/mob/creating-and-publishing-documentation

fix(techdocs): remove unused doc files and merge some docs into one file

docs/features/techdocs/README.md

@@ -36,11 +36,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
 
 - [Getting Started]
 - [Concepts]
-- [Reading Documentation]
-- [Writing Documentation]
-- [Publishing Documentation]
-- [Contributing]
-- [Debugging]
+- [Creating and Publishing Documentation]
 - [FAQ]
 
 ## Tech Stack
@@ -54,11 +50,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and
 
 [getting started]: getting-started.md
 [concepts]: concepts.md
-[reading documentation]: reading-documentation.md
-[writing documentation]: writing-documentation.md
-[publishing documentation]: publishing-documentation.md
-[contributing]: contributing.md
-[debugging]: debugging.md
+[creating and publishing documentation]: creating-and-publishing.md
 [faq]: FAQ.md 'Frequently asked questions'
 [techdocs/frontend]:
   https://github.com/spotify/backstage/blob/master/plugins/techdocs

docs/features/techdocs/contributing.md

@@ -1 +0,0 @@
-# Contributing

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

@@ -1,11 +1,21 @@
-# Publishing Documentation
+# Creating and publishing your docs
+
+This section will guide you through:
+
+- Creating a basic setup for your documentation
+- Writing and previewing your documentation in a local Backstage environment
+- Creating a build ready for publication
+- Publishing your documentation and making your Backstage instance read from
+  your published docs.
 
 ## Prerequisities
 
 - [Docker](https://docs.docker.com/get-docker/)
 - Static file hosting
+- A working Backstage instance with TechDocs installed
+  [TechDocs getting started](getting-started.md)
 
-## Create documentation
+## Create a basic documentation setup
 
 Create a directory that contains your documentation. Inside this directory you
 should create a file called `mkdocs.yml`. As an example you can create a
@@ -32,7 +42,23 @@ And then the `~/hello-docs/docs/index.md` should have the following content:
 This is a basic example of documentation.
 ```
 
-## Build documentation
+## Writing and previewing your documentation
+
+Using the `techdocs-cli` you can preview your docs inside a local Backstage
+instance and get automatic recompilation on changes. This is useful for when you
+want to write your documentation.
+
+To do this you can run:
+
+```bash
+cd ~/hello-docs/
+npx techdocs-cli serve
+```
+
+## Build production ready documentation
+
+To get a build suitable for publication you can build your docs using the
+`spotify/techdocs` container.
 
 ```bash
 cd ~/hello-docs/

docs/features/techdocs/debugging.md

@@ -1 +0,0 @@
-# Debugging

docs/features/techdocs/reading-documentation.md

@@ -1 +0,0 @@
-# Reading Documentation

docs/features/techdocs/writing-documentation.md

@@ -1 +0,0 @@
-# Writing Documentation