Documentation

So you have written an application, a library or whatever it is that you have decided to create. Now you need to document the service so that others can know how to use it, how to configure it and so on.

So where do we document this?

Yes you can use tools like confluence, or some other platform. Some even prefer to just use google docs to document the service.

In our case, we rejected this option since we wanted the documentation to be correlated with the code. The same PR that changes the code must also update the documentation (else we know that no one will update the documentation :) ).

Markdown

So what do most people do? It seems that most will go to the option of creating markdown files in the git repo. This seems fairly standard and easy, but the end result is not that great. It does document the service, and you have links between files, but the visual side is very slim.

So what we are looking for is to be able to write markdown files but have an engine to generate a documentation site for browsing and searching information.

Well it seems there are few options for this in the market.

Github pages

If you are a GitHub fan you have the pages as an option. You can create pages that are markdown files that are then generated as a site.

We decided not to go with pages since it is a bit simplicity. Instead we used another platform called backstage. Backstage is a product that is more than just documentation. It includes service discovery, monitoring — and is more or less a central hub for all information about your services.

Mkdocs

I did spend time to create the GitHub pages, to just then go and learn yet another tool of backstage documentation. That is when I ran into mkdocs. It is a plugin of backstage for documentation, but it is much more. It is a bridge for generating documentation site for other frameworks. It can generate a site by its own, and it can export to GitHub pages or backstage.

Another advantage of using mkdocs is that you can view the web site locally, update the documentation and view then changes very quickly. You do not need to commit the code in-order to build and view.

It is based on python, so a simple

pip install mkdocs

is enough to install it. From there you have simple commands like build and serve to view locally the web site.

Backstage

Backstage is a full product that has incorporated mkdocs into it. It also has its own tools for local viewing — techdocs-cli. This tool is installed via

npm install -g @techdocs/cli

and can then be run using build and serve. But this tool is much more heavy weight than mkdocs, so I usually stay away from it.

For further performance it is better to generate the web site only if the documentation has changed and not on every view with caching. To do this there is a great script for GitHub actions, to copy the compiled site to S3.

Summary

Code and documentation need to be written within the same cycle. The PR for you code must include the documentation for it. This does not mean that you need to give up on a nice functional documentation site. For simple uses you can go with GitHub pages, and for a fuller experience go for backstage.