Docs-as-Code explained: Benefits, tools and best practices

The importance of Docs-as-Code

In today's competitive business climate, every organization must focus on its customers and increasing speed to market. This means increasing both velocity and quality while managing cost. By creating documentation simultaneously alongside coding, Docs-as-Code both streamlines the software development process and increases the quality of the code. Docs-as-Code also supports a focus on customer service because it increases accountability for documentation.

Docs-as-Code benefits

The Docs-as-Code methodology improves the SDLC in several ways. Benefits derive from simultaneously writing documentation and developing code, as well as from using a shared tool stack.

Benefits of implementing Docs-as-Code include the following:

• Enhanced focus on documentation.
• Quality improvement.
• Cross-team collaboration.
• Improved standardization, consistency and maintenance.

Enhanced focus on documentation

Although documentation is one of the most critical aspects of the SDLC, it's often ranked low in importance and is sometimes delayed, especially when the project falls behind schedule. When developers implement Docs-as-Code, it not only provides a focus on documentation, but more importantly, it ensures that documentation receives a high level of priority.

Quality improvement

The Docs-as-Code methodology improves quality in several ways. When teams produce documentation concurrently with development, they can recognize ambiguities in the requirements earlier in the SDLC. Functional and non-functional testers, UX engineers and user acceptance testers can use the documentation to understand the code. This facilitates more effective test coverage because testers can optimize the test suite by focusing test cases on critical functionality and on the most complex parts of the code. 

Using documentation to enhance testing is especially important in security and other non-functional testing areas, as bugs can be found earlier in the process. Bugs in non-functional areas are often among the most difficult to fix, especially when they are found late in the development process. Finding them as early as possible increases quality and reduces the cost.

Cross-team collaboration

Docs-as-Code enables developers and documentation authors to more easily work together in a shared space because they use the same tool stack for both code and documentation. Maintaining documentation in a shared space increases its accessibility and encourages frequent updates. 

Improved standardization, consistency and maintenance

A standard tool set enables developers to format documentation consistently, which simplifies maintenance. This does not mean that documentation is automatically updated; updates must be scheduled into the workflow. However, by following best practices such as version control, CI/CD pipelines and test automation, team members can stay accountable for ensuring documentation remains continuously maintained.

The Docs-as-Code process

The Docs-as-Code process is as follows:

1. Draft the documentation.
2. Develop the code.
3. Share the documentation and code for review.

Developers review the documentation along with the code to ensure both meet the requirements. The documentation must accurately reflect the code before approval. Version control tools can enable this alignment. Once the managers have approved the documentation, developer teams publish it on a hosting platform. Most importantly, the CI/CD pipeline manages and automates the process.

The Docs-as-Code tool stack

The core end-to-end tool stack for Docs-as-Code includes tools that meet the needs of each part of the process. The core types of tools include the following:

• Documentation and code generators.
• Version control tools.
• Hosting applications.
• CI/CD pipeline tools.

Depending on the domain and the type of software under development,  additional tools that facilitate the Docs-as-Code are available. 

Documentation and code generators

Examples of documentation and code generators are the following:

• Markup languages. Collections of rules in a text-based system that specify the structure, format and presentation of documents. Markdown is one of the most popular markup languages for documentation, as it uses plain text formatting.
• Integrated development environments. Software applications used for coding and software development. IDEs such as VSCode and IntelliJ are popular choices because they support both coding and documentation.
• Static site generators. Software applications used to build websites. Developers can use SSGs, such as MKDocs, Jekyll and Hugo to build and publish websites. Docusaurus is another SSG that uses Markdown with React, making it suited for projects that involve high volumes of documentation.

Version control tools

Version control tools can track and manage changes in the documentation and code. Although Git is the most common tool, AWS CodeCommit, Mecurial and Helix Core are also in use.

Hosting applications

GitHub, Bitbucket and GitLab are publicly hosted repositories that are frequently used in Docs-as-Code tool stacks.

CI/CD pipeline tools

The most widely used tools for creating and managing CI/CD pipelines include GitHub Actions, Jenkins and GitLab CI/CD. These can automate, test and deploy both documentation and code, as well as manage changes. 

Additional tools

Finally, tools such as SWIMM and Doxygen can orchestrate the entire Docs-as-Code process from generation through release. If the application relies heavily on APIs, tools such as Swagger, Readme.io or OpenAPI can increase the velocity and quality of API documentation. In addition, linters such as MarkdownLint and Vale are useful for ensuring consistent formatting.

Buying considerations

The selection of the tool stack will play a key role in the effectiveness of Docs-as-Code implementations. Because using the same tool stack for both code and documentation can keep everything coordinated, it is important to choose integrated tools that are appropriate for both tasks. This helps developers identify and address mismatches between documentation and code.

A best practice when designing the tool stack is to review the tools already in used in use in the SDLC. When teams make more use of the tools already a part of the current SDLC, it not only reduces cost but also facilitates the change management required to implement the Docs-as-Code process, as teams are already familiar with those tools.

Furthermore, when designing the tool stack and planning the implementation, it's important to consider the cost of the tools themselves, as well as the costs associated with installation, integration and training for the team. Finally, consider the costs involved in maintenance and upgrades, especially with SaaS products.

Best practices for Docs-as-Code implementations

Best practices when implementing Docs-as-Code include the following:

• Obtain buy-in from teams. It is crucial for project teams to understand the benefits of Docs-as-Code and be on board with the implementation.
• Plan for security. Security is especially important in the hosting repositories and CI/CD pipelines to protect data from potential breaches.
• Emphasize collaboration. Active participation from all team members is a key factor in the success of Docs-as-Code.

Gerie Owen is a QA engineering manager at Roobrik. She is a conference presenter and author on technology and testing topics, and a certified Scrum master.