From 38e9eb419afa4482d1fcdbf952c5c61aebdbe280 Mon Sep 17 00:00:00 2001
From: ellinors <ellinors@spotify.com>
Date: Wed, 15 Jul 2020 16:36:05 +0200
Subject: [PATCH] docs(techdocs): Updated documentation on how to publish
 documentation in TechDocs.

---
 .../techdocs/publishing-documentation.md      | 85 ++++++++++++++++---
 1 file changed, 73 insertions(+), 12 deletions(-)

diff --git a/docs/features/techdocs/publishing-documentation.md b/docs/features/techdocs/publishing-documentation.md
index 279791da93..73ac74b458 100644
--- a/docs/features/techdocs/publishing-documentation.md
+++ b/docs/features/techdocs/publishing-documentation.md
@@ -1,18 +1,18 @@
 # Publishing Documentation
 
-## Prerequirsities
+## Prerequisities
 
 - [Docker](https://docs.docker.com/get-docker/)
 - Static file hosting
 
 ## Create documentation
 
-Create a directory that contains your documentation. The directory should have a
-file called mkdocs.yml. As an example we will(you can?) create a directory
-called `hello-docs` in your home directory. Below is a basic example of how it
-could look.
+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
+directory called `hello-docs` in your home directory (also known as `~`). Below
+is a basic example of how it could look.
 
-`~/hello-docs/mkdocs.yml`
+The `~/hello-docs/mkdocs.yml` file should have the following content:
 
 ```yaml
 site_name: 'example-docs'
@@ -24,9 +24,9 @@ plugins:
   - techdocs-core
 ```
 
-`~/hello-docs/docs/index.md`
+And then the `~/hello-docs/docs/index.md` should have the following content:
 
-```yaml
+```md
 # example docs
 
 This is a basic example of documentation.
@@ -36,12 +36,73 @@ This is a basic example of documentation.
 
 ```bash
 cd ~/hello-docs/
-docker pull spotify/techdocs
-docker run -it -w /content -v $(pwd):/content spotify/techdocs
+docker run -it -w /content -v $(pwd):/content spotify/techdocs build
 ```
 
 You should now have a folder called `~/hello-docs/site/`.
 
-## Deploy to a server
+## Deploy to a file server
 
-## Configure TechDocs to read from server
+In order to serve documentation to TechDocs, our Backstage plugin needs to
+download the HTML rendered from the
+[Create documentation](#create-documentation) step above. This will likely exist
+on an external file server, or a storage solution such as Google Cloud Storage.
+
+When deploying documentation, it should be deployed on that file server /
+storage solution with the following convention: `{id}/{file}`. For example, if
+we wanted to upload the `getting-started/index.html` file for the `backstage`
+documentation site, we would upload it to our file server as
+`backstage/getting-started/index.html`.
+
+To explain further how this would look like for multiple documentation sites,
+take a look at this example file tree that would be represented on your file
+server:
+
+```md
+/backstage/index.html /backstage/getting-started/index.html
+/backstage/contributing/index.html /mkdocs/index.html
+/mkdocs/plugin-development/index.html
+/mkdocs/plugin-development/debugging/index.html
+```
+
+In this file tree, we have two documentation sites available: `backstage` and
+`mkdocs`. Each of them expose several pages. Let's say both of these are hosted
+on `http://example.com` as the server URL.
+
+When you configure the TechDocs plugin in Backstage to use `http://example.com`
+as the file server / storage solution, it will translate the following URLs to
+the file server:
+
+| Backstage URL                                             | File Server URL                                         |
+| --------------------------------------------------------- | ------------------------------------------------------- |
+| https://demo.backstage.io/docs/backstage/                 | http://example.com/backstage/index.html                 |
+| https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |
+
+Then deploying new sites is easy. It's as simple as copying over the `site/`
+folder produced in the [Create documentation](#create-documentation) step above
+and copying it over to the file server / storage solution under the ID of the
+documentation site. It will then become immediately available in Backstage under
+the same ID as you can see in the table above.
+
+So, if the URL to your file server is `http://example.com/`, your
+`~/hello-docs/site` folder containing the documentation should be accessible at
+`http://example.com/hello-docs/`.
+
+## Configure TechDocs to read from file server
+
+In order for Backstage to show your documentation, it needs to know where you
+uploaded it.
+
+Make sure you have Backstage set up using
+[TechDocs getting started](getting-started.md)
+
+To point Backstage to your docs storage, add or change the following lines in
+your Backstage `app-config.yaml`:
+
+```yaml
+techdocs:
+  storageUrl: http://example.com
+```
+
+You can now start Backstage using `yarn start` and open up your browser at
+`http://localhost:3000/docs/hello-docs` to view your docs.