A new solution to documentation

What Spotify’s Backstage means for documentation

Developer portal that places priority on documentation

In this article I will be taking a closer look at Spotify’s Backstage plugin TechDocs. Backstage is a centralized service catalog. One of Backstage’s plugins, called TechDocs, offers a much needed documentation solution.

TechDocs lets the developers write in markdown and that documentation lives with the code, embracing the docs-like-code philosophy and allowing for a centralized place for the docs to be read. The Backstage documentation suggest that more syntaxes will be supported like rst and AsciiDocs.

TechDocs Core Plugin is built with MkDocs, which is a light-weight static site generator that creates a “wrapper around multiple MkDocs plugins and Python Markdown extensions to standardize the configuration of MkDocs used for TechDocs.” [1] By default, the documentation is shipped with MkDocs Material Theme.

Furthermore, Spotify’s docs-like-code solution is built around docker. The TechDocs container allows your infrastructure to be built in a repeatable and safe manner. The TechDocs Reader lets users spin up reconfigured static HTML sites.

By default Backstage has documentation templates that allow you to easily spin up documentation. It works similarly to other static site generator with a UI wrapper, meaning you create a Docs folder with index.md to define the structure of your site.

I like the cli that TechDocs comes with. The techdocs-cli command allows you to run an instance of your documentation for you to preview before the docs go live.

My thoughts are that this is a step in the right direction to offer a developer portal that gives a great documentation experience. The ability to see the documentation and edit directly on GitHub means it is developer friendly.

If you’re looking to understand the plugin a little more, Spotify has a great intro video you can watch here.