Should You Use Docs-as-Code?

So you’ve heard about docs-as-code and are wondering if it’s right for your project. When deciding whether to implement docs-as-code for your documentation projects, it’s essential to weigh the unique aspects of your project, such as quality standards, project requirements, and the nature of contributions. Understanding the benefits and requirements of docs-as-code will help you make an informed decision on whether it’s the right approach for your specific needs. In this article we’ll discuss some of the key considerations when deciding whether to use docs-as-code.

Balancing Quality Standards and Project Requirements

Every documentation project has unique quality standards and expectations. For internal documentation, the focus is often on accessibility and ease of use for company employees, making minor imperfections more acceptable.

On the other hand, external documentation demands a higher level of precision, especially for technical software products like APIs that other developers rely on. In these cases, the documentation directly reflects the quality of the product itself, as there may be no other user interface. For Software-as-a-Service products, while documentation quality remains important, surgical precision and constant updates may not be as critical.

Docs-as-code facilitates the creation of clear, accurate, and high-quality documentation by integrating objective quality standards and the review process.

• Implement automated tests and validation tools to identify issues such as broken links, formatting inconsistencies, and content errors during the review process.
• Enhance the review and feedback process with version control and change tracking systems, similar to code repositories.
• Foster collaboration among developers, technical writers, and other stakeholders to ensure documentation accurately captures the product’s features and functionality.
• Pair documentation with code changes, ensuring that documentation is updated as the code changes and their history is linked.

Projects with any type of quality standards can benefit from docs-as-code as it’s up to the project team to determine the level of quality they want to maintain, whether it’s strict or a bit more relaxed.

Contribution Dynamics

The advantages of docs-as-code become more apparent based on how people contribute to your project. Adopting docs-as-code is particularly beneficial when:

• You have an extensive team of developers, technical writers, and other stakeholders contributing to the documentation.
• or, your project is open source, welcoming external contributions.

The degree of docs-as-code implementation one should aim for depends on the contributors’ profiles. When developers and other stakeholders without professional writing experience contribute to the project, it’s crucial to employ automated quality checks and other safeguards to uphold documentation standards. When doing so, it is equally important that the rationale behind such checks is communicated clearly to avoid confusion.

However, if your team consists of a smaller group of professional writers, these measures may be less of a priority.

Evaluating Automation Potential

Assessing the potential to automate aspects of your documentation process plays a crucial role in deciding whether to embrace docs-as-code.

If your product incorporates OpenAPI specifications, code comments, code examples, or other design artifacts, docs-as-code can save you time and minimize manual effort.

Integrating the documentation process into your development workflow enables you to:

• Generate API documentation automatically from OpenAPI specifications, guaranteeing accuracy and consistency throughout your documentation.
• Extract documentation from code comments or annotations, decreasing duplication and keeping the documentation current as the code changes.
• Derive code examples directly from your source code, offering users precise and relevant examples that mirror your product’s current state.
• Automatically track documentation tasks in version-control linked trackers such as Linear so that they can be handled in a way similar to other product-related tasks.

By evaluating the automation potential in your documentation project, you can better determine if docs-as-code is the right approach for you.

Conclusion: Is Docs-as-Code Right for Your Project?

Docs-as-code offers a powerful solution for maintaining and enhancing your documentation quality. To determine if it’s the right fit, consider your project’s unique requirements, contribution dynamics, and automation potential. While not an exhaustive list, the following scenarios can help guide your decision:

• Your project depends on design artifacts like OpenAPI specifications, code comments, or code examples, and automation could significantly reduce manual effort when keeping your docs up to date.

• You’re working on a project with specific quality standards and a diverse team of contributors. Automated quality checks, validation tools, and a robust review process are essential for preserving documentation quality.

• You have a sizable engineering team that requires accurate internal documentation for various interfaces. Developers are the primary contributors.

• You’re managing an open-source project with a diverse range of contributors, where efficient collaboration, version control, and review processes are crucial.

• Your project includes maintaining and updating documentation for multiple versions of a product separately.

Consider adopting docs-as-code if any of these scenarios apply to your project. If multiple points resonate, you should definitely implement docs-as-code.