Docs-as-Code

Docs-as-Code is the approach of writing documentation the same way we write code. When coding, we create classes, functions and tests with simple text files. These text files can be written and read by any editor and get compiled into beautiful software products. People with knowledge of the language understand the syntax easily and feel comfortable working with these files. The files can be easily adapted as well. We can also put those simple text files under version control, branch off, create a pull request and let our colleagues review our changes to follow a four-eye principle for improving code quality.

With a Docs-as-Code approach we want to achieve the same: As developers, we want to work on the documentation in simple text files which we can understand easily and read and write with every editor. We want to use our existing version control system and a pull request workflow. But how can we implement that? Do we really want to leave our simple What-You-See-Is-What-You-Get proprietary tool? With this we can easily format a headline, but we then have to reformat the whole document if we change a word to bold. Do we really have to write LaTeX and read the meaning of a portion of text from hard-to-read Markup?

But wait: There is an intermediate solution! We can write text files in either Markdown, Asciidoc, or reStructuredText (ReST) and still have headlines, tables, ordered and unordered lists in a nice „Lightweight Markup Language“ view in plain text files.

Structured Text Formats for Developers

As an example, with ReST a headline followed by a list would look as follows:

This is my headline
===================

The List starts here
- first item
- second item

The same in Markdown would look like this:

# This is my headline

The list starts here:
 - first item
 - second item

As we can see, this is still well readable but written in a simple text format. Some IDEs can even interpret this and output it nicely. They present them with bigger fonts for headlines and italics, or bold highlights on the corresponding directive while editing the code.

These simple text files can be put under version control. We can use a pull request workflow to keep the documentation correct. Actually, this is also what we did while writing this article. We used a repository on GitLab and let a second engineer review the blog article. We can also enforce granular access control to the repository holding the documentation to restrict who can write it.

Writing the documentation becomes easier for the developers if they can use the workflow they are used to. Developers tend to perform all of these steps anyway, so this can be an incentive for them to document more. The developer’s workflow might also be driven by user stories, where they can see their changes to the documentation right next to or within the changes on the code.

Generated Documents for Readers

With tools like Pandoc, Asciidoctor, or Sphinx we can create output formats like HTML and PDF as attractive documentation for different target groups like for instance developers, managers or auditors. From Pandoc we can create all kinds of output styles, even Microsoft Word formats. Sphinx is also able to generate HTML, LaTex (via pdflatex also to PDF), ePub and other files. Let’s look a little more closely at one of these tools: Sphinx.

Extensions for Sphinx: Beyond textual documentation

Sphinx isn’t only a tool to generate HTML from ReST. We can set up variables, which we can use throughout the whole document. If we write documentation for our project „ABC“, we can:

Set up a variable for the project name „ABC“ and use the variable name inside the documentation. In case our project name changes – for example from an internal project name „ABC“ to a public one – we can change the name in one single spot. The created document will then use the new name everywhere.
Implement an auto-generated changelog chapter from our version control system. With the use of CI/CD it is also possible to add information about the product to the documentation by appending the software bill of materials (SBOM).
Use extensions to link requirements to their fulfillment documentation.
Create UML diagrams within the plaintext documentation using the plantuml extension for Sphinx.
Extend Sphinx with additional, self-written directives. We can set up a directive that computes the CVSS3.1 risk rating of a vulnerability from its vector with:
```
.. cvss:: CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H
```
This would then output a base score of 10.0 and maybe set a red background color in the resulting document. This visualization can also vary between various documentation output types.

…and many more!

To conclude, using a Docs-as-Code approach in a pull request workflow with CI/CD provides us with many advantages: Great flexibility, high acceptance from the people (e.g., developers) who have to write the documentation and nicely generated output for every relevant stakeholder. If you want to learn more about this, feel free to contact us.