Documentation as a Code

Introduction

Documentation as Code (DaaC) is an approach that emphasizes treating documentation as an integral part of the code. While it may sound simple, putting it into practice can be a bit tricky. DaaC essentially "forces" engineers to treat documentation as they would treat source code. This includes using tools that are commonly employed when working with code, such as Versioning Tools, Bug Trackers, Unit Tests, and others.

Problem

When asked a simple question like, "Is documentation important?", almost everyone would agree that the answer is "Yes, documentation is important.". However, oddly enough, even though engineers recognize the importance of documentation, they are not typically "obsessed" with it. In other words, engineers understand the value of documentation, but they are often reluctant to write it. Sounds familiar?

There are several reasons for this mindset:

1. Documentation is perceived as an additional burden. This perception arises from the belief that documentation is not code. Naturally, engineers assume that documentation is not part of their job, and writing it means taking on extra work outside of their primary responsibilities, which can be seen as an added burden.
2. Documentation is the job of Technical Writers. This assumption is not entirely wrong, but it is not entirely correct either. There are many instances where only an engineer can write certain types of documentation, such as Reference Docs.

Often, engineers do not prioritize documentation due to their workload and the perception that it is not directly related to their core responsibilities. This can lead to outdated, incomplete, or missing documentation, which can impact the overall quality and maintainability of the software.

Solution

DaaC can be a solution to bridge the gap between the importance of documentation and the mindset of engineers. DaaC considers documentation to be part of the code. This simple statement changes a lot about how documentation is treated, including:

1. Writing documentation is an engineer's responsibility.
2. Documentation should be included in versioning tools.
3. Documentation must be checked and tested for format and validity. These checks and tests can be performed within the Build Pipeline as they are done for code.
4. Documentation should be aggregated into a single portal accessible and reviewable by the internal team.
5. If documentation is not compliant in terms of format or content, it is considered a bug. This bug must be recorded in the Bug Tracker, assigned to an engineer for resolution, and checked again after being fixed. Remember this proverb:

The only thing worse than no documentation is bad documentation

DaaC is designed to change the mindset of engineers by integrating documentation as a fundamental aspect of the software development process. By treating documentation as code, engineers are encouraged to maintain a high standard of quality, just as they would for their codebase.

Here are some additional benefits of DaaC:

• Improved collaboration: By using version control systems and code review processes for documentation, engineers can work together more effectively to create and maintain high-quality documentation.
• Easier maintenance: Treating documentation as code makes it easier to keep it up-to-date, as it becomes an integral part of the development process.
• Better communication: DaaC can help bridge the gap between engineers and non-technical stakeholders, such as product managers and designers, by providing a centralized and accessible source of information about the software.

Technology Stacks

At 8grams, we use tools already in use for source code to implement DaaC.

GitLab (Code Repository, Code Review, & CI/CD Tools)

Documentation that is part of a project, such as Readme and docstrings, will automatically be included in versioning tools. For docstrings specifically, we use several libraries for checking and reviewing:

1. pydocstyle - This library ensures that each module and function has a docstring that complies with the proper format. It also checks the docstring coverage level of a project. If the coverage level falls below a certain threshold, the application will fail to build (see image below).
2. Sphinx Docs - This library generates docstrings in HTML format. The resulting HTML files are built into a new image that is deployed to a subdomain accessible to the internal team. See the rev.Dockerfile to learn how these documentation files are built into a ready-to-deploy image (see image below)..
3. Docsify - For aggregating documentation into a single portal, the Docsify framework is used in the 8grams. This project generates a documentation portal from markdown files. Another alternatives are using static site generators: tools like Jekyll, Hugo, or MkDocs can be used to convert documentation written in Markdown or reStructuredText into a static website, which can then be easily deployed and hosted.

Redmine

Redmine serves as a bug tracker for invalid, expired, or incorrect content in documentation. At 8grams, each project will have dedicated tracker in Redmine to track all bugs and tweaks related to the project's documentation.

Policy

8grams follows an unwritten rule regarding DaaC:

1. Merge Requests will not be approved or merged if docstrings are missing.
2. Each engineer is required to write a comprehensive description (consisting of ideas, concepts, and implementation examples) when implementing a feature. See the description of App Notifications as an example.

Reference

You can learn more about the concept at https://cchesser.github.io/docs-as-code/. As a bonus, below is our presentation about DaaC. Enjoy it!

About 8grams

We are a small DevOps Consulting Firm that has a mission to empower businesses with modern DevOps practices and technologies, enabling them to achieve digital transformation, improve efficiency, and drive growth.

Ready to transform your IT Operations and Software Development processes? Let's join forces and create innovative solutions that drive your business forward.

Subscribe to our newsletter for cutting-edge DevOps practices, tips, and insights delivered straight to your inbox!