Docs as Code: where to start?

Docs as Code is an approach to creating software documentation using the same tools and processes as for writing code. Generally speaking, it’s about treating documentation similarly to code.

Documentation following the Docs as Code approach uses the same source control as for the code (usually, git) and resides either in the same repository as code (preferably) or in a separate one.

In contrast to binary formats (like Microsoft Word or Adobe FrameMaker) and markup previously mostly used for documentation, the documents following the Docs as Code approach are created using plain text formats like markdown, reStructured Text, or AsciiDoc. These don’t require any specific tools – just any text editor, like VS Code, Sublime Text, or simply the one preferred by the development team. The only thing an Information Developer needs to select is a static site generator (SSG) to compile the final output.

Depending on the product needs, content structure, and the final output, this can be:

• MkDocs (perfect for technical documentation, simple in configuration)
• Docusaurus (great for documentation portals and API documentation)
• Sphinx (if you need reStructuredText, great for documenting Python libraries and scientific docs)
• Hugo (great for creating multilingual documentation, fast in performance for large-scale documentation)
• Any other SSG that responds to the project's needs.

Collaboration and integration with development

The idea of the Docs as Code approach is to introduce synergy and collaboration in the development team, making documentation available and understandable to anyone who is willing to contribute, at the same time, preserving rules and standards and making it consistent.

This approach requires Information Developers (Documentation Engineers) to work closely with DevOps and Software Developers to integrate documentation into the development pipeline, including CI/CD setup to build target files.

Additionally, with the Docs as Code approach, documentation quality checks can be automated by adding linters (e.g., Vale, markdownlint, etc.) to the documentation development pipeline. Thus, the process becomes even more streamlined, making sure that the documentation is consistent in style, formatting and terminology, grammatically correct, and does not contain any technical issues like broken links.

What’s great about the Docs as Code approach is that it allows following the usual code review process for documentation, engaging SMEs not only to contribute to documentation, but also to validate and approve the written chunks of content before they are published. This is done as a part of the usual development process, without the need to set up extra calls, contact SMEs multiple times, or escalate the need for review before publishing.

With all this, documentation following the Docs as Code approach makes updates fast and automates publishing.

Post

Discover the stages of the software product life cycle

Read more

Common challenges in documentation written following the Docs as Code approach

According to the Docs as Code philosophy, the approach works no matter the number of people contributing to the documentation. However, you should be aware from the start that the more people start contributing to documentation, the more well-thought-out the documentation process set up should be. You need to think well on the following aspects to make your project benefit from the Docs as Code approach rather than struggle with it:

• Code review ensures only the factual correctness of the documentation chunks. Linters and automated quality checks are great, but they do not replace the documentation governance process altogether. Therefore, you’ll need an additional part of the process and an Information Developer on the team whose responsibility will be to validate the added chunks of information and make sure they form understandable and clear information architecture rather than just a bulk of autonomous and misleading chunks of information.
• You need to have a well-established and documented process of automated publishing of the documentation – don’t make one person on your team the only knowledge holder of the process, and a bottleneck.
• Have a documented set of rules for documentation available in your team knowledge base. It should not be overly detailed or burdensome, but should definitely capture the most important points to make sure everyone is on the same page.
• With team growing, you should take into consideration that the learning curve for non-techy documentation engineers is too high – you would need to specifically hire tech-savvy Information Developers who are not afraid of Markdown, git, or CI jobs.
• Markup does not provide means for smart content management out of the box. So, to make documentation production more efficient and include single sourcing, content reuse, or advanced content structuring, you need to search for specific plugins or develop custom solutions.

With all considerations in place, Docs as Code approach works as a charm in software teams, making documentation fully synchronised with the development process, keeping it as an inseparable part and feature of a product rather than a strange citizen who is always late.