Documentation as code: A revolutionary innovation for DevOps teams?

Documentation as code (DaC) is a growing trend in the software development world. This approach treats software documentation in the same way as software code. In other words, documentation is written, managed, stored and delivered in the same way as code, facilitating efficient and effective collaboration between development and operations teams.

Treating documentation as code allows one to create a shift-left approach, meaning that documentation is produced and updated as soon and as often as possible. This results in more accurate, up-to-date and relevant documentation, as it is updated as the code changes. Because documentation is treated as code, it becomes part of the development process, not an afterthought. This helps bridge the gap between development and operations, making it easier for teams to deliver high-quality software faster.

5 principles of the DaC concept

1. Version management

Version control is a key tool for documentation as code. As with a code base, documentation constantly changes and evolves. Old features are deprecated and removed, new features are added, and bug fixes are added. This is why it is necessary to keep track of changes and have the possibility to easily revert to previous versions if necessary.

Version control systems such as Git are also perfect for managing documentation. They allow you to keep track of changes, create different versions of documents and merge changes to different parts. This makes it easier to collaborate on documentation and ensures that there is always a record of changes.

2. Simple text formats

Another basic principle for managing documentation as code is the use of plain text formats such as Markdown or reStructuredText. These are easy to read and write, and support version management and comparison of different versions.

In addition, plain text formats are platform-independent, which means they can be read and edited on any operating system. This is a huge advantage over closed formats such as Word, which require special editing software and are not necessarily compatible across platforms.Furthermore, if you need to publish documentation, plain text formats can be easily converted to other formats such as HTML or PDF.

You can therefore write documentation in plain text format and then generate different output formats for different purposes or audiences.

3. Collaboration and peer review

DaC facilitates collaborative work because the documentation is stored in a simple text format in a version control system, so it can be easily accessed by any member of the team. Developers, testers, operators and even customers can contribute to the process, resulting in more comprehensive and accurate documentation.

In addition to facilitating cooperation, documentation as a code also encourages peer review. As with code, documentation can be improved by having other people review it. This can help identify errors, improve transparency and ensure consistency. Version control systems have built-in tools for code validation, which can also be used for documentation. This allows developers to check and improve the quality of the code, and these tools can help detect possible bugs or defects.

For example, in a merge request, developers can add comments and observations to the code, which can then be included in the documentation.

4. Automated testing and deployment

Like code, documentation can and should be tested automatically, helping to detect errors such as incorrect links, missing images and incorrect formatting. There are a wide range of tools available that can automatically test documentation and can be integrated with CI/CD (Continuous Integration and Continuous Deployment) processes to automatically update documentation when the code base changes.

In addition to testing, documentation can also be delivered automatically. For example, when documentation is revised, the CI/CD pipeline can automatically upload the updated documentation to the website or documentation portal during deployment. This ensures that documentation is always up-to-date and corresponds to the current state of the software.

5.Single Source Of Truth

The final principle of the DaC concept is the so-called, "Single Source Of Truth" (SSOT) approach. The SSOT concept means that there is only one single, trusted source for data or information where it is stored and maintained. The DaC concept also follows this principle, whereby all data or information is derived from a central source and all other systems, applications or processes rely on this single source.

The benefits of the SSOT approach include consistency, reliability and simplicity. Using the same data source, there is less chance of error and development processes become more efficient, thanks to easier data availability and maintenance.

This concept therefore ensures consistency across all versions of the documentation, and also makes it easier to manage and update the documentation, as only one source needs to be updated.

The benefits of code-based documentation for DevOps teams

Better collaboration

In traditional systems, documentation is often treated as a secondary consideration and often only addressed after the actual coding is complete. However, with the DaC concept, documentation becomes an integrated part of the code. In doing so, it promotes responsibility sharing and better understanding, and encourages a culture of collaboration.

Improved consistency and accuracy

The DaC approach ensures that documents meet predefined standards and are error-free. It automatically checks for consistency in phrasing, formatting and structure, eliminating manual work and minimizing the potential for human error. In addition, documentation is included with the code, so it always accurately reflects the current state of the system.

Optimized updating and support processes

Traditional documentation often quickly becomes outdated, requiring significant time and effort to update. But with DaC, updates become an integrated part of the development process. As the code changes, the documentation is updated automatically, solving the problem of having to update separate documentation to keep it up to date.

DaC best practices for DevOps teams

Here are some best practices to help you effectively implement documentation as code in your DevOps processes.

Get started early!

One of the most important pieces of advice is to start documenting as soon as possible, indeed from the very first line of code! This will ensure that documentation evolves organically with the code, and reduces the likelihood that important details are forgotten or missed.

Use simple markup languages

When implementing DaC, it is advisable to use light markup languages such as Markdown or AsciiDoc. They are easy to learn and use, and allow you to write documentation that is easy to understand in both raw form and HTML or other formats.

Documentation review and feedback process

As with code reviews, documentation reviews should become a regular part of the development process. This will ensure that the documentation is accurate and comprehensive, and that it meets the standards used by the team. We recommend that you build a feedback process into the documentation process. This will allow the team to continuously improve the documentation based on the feedback from users and stakeholders.

Modular design and multi-use

And finally, design your documentation with modularity and reusability in mind. Break it down into small, manageable parts that can be easily updated and reused in different parts of the application.

Summary

In our opinion, properly-prepared documentation is an invaluable tool for DevOps teams, as it improves collaboration, ensures consistency and accuracy, facilitates version management and simplifies update and maintenance processes. By following the points in the list of best practices outlined above, you will be guaranteed to harness the potential of the DaC method and significantly increase your team's efficiency and effectiveness.

At Devertix, we have decades of experience in designing and implementing DevOps processes. If you'd like to assess the state of your DevOps processes, we recommend you take our free DevOps maturity survey. And if you're looking to take your DevOps to the next level or implement the right documentation process but don't know what the best practices and supporting tools are, contact us and we can help!