Why Docs-as-Code is the Key to Better Software Documentation

Introduction

In the software development ecosystem, there is often friction between software developers and technical writers when it comes to creating and contributing to software documentation. One reason for this issue is that these two key players often use different methods for publishing their work. However, wouldn't it be beneficial if software developers could collaborate with technical writers in writing and managing software documentation?

The answer is YES, it is possible, but only with the Docs-as-Code approach. To understand how this can be achieved, let's dive deeper into what the Docs-as-Code approach entails.

In this post, you will learn about managing technical documentation in the same way a developer handles code, known as the Doc-as-Code (DAC) approach, and why team leaders and technical writers should adopt it.

Docs-as-Code (DaC)

In technical writing, many approaches have been used by technical writers for writing, publishing, and maintaining technical documentation. Previously, technical writers used Database CMS tools such as WordPress, Hippo, and others, which did not encourage contributions from other users, such as developers, to the documentation.

It was not until October 19, 2000, that Tom Preston-Werner, co-founder of GitHub, had an idea about the Docs-as-Code (DaC) approach.

In a blog post, Blogging Like a Hacker, he states,

"What would happen if I approached blogging from a software development perspective? What would that look like?"

The question above gave birth to the Docs-as-Code approach.

What is Docs-as-Code?

Docs-as-code is an approach to writing and publishing documentation with the same tools and processes developers use to create code. In short, the DaC approach uses the same systems, processes, and workflows with docs as you do with programming code.

Processes of the Docs-as-Code approach

The Docs-as-Code approach comprises:

• Writing reStructuredText or Markdown in plain text files.
• Developing the documentation website using an open-source static site generator like Sphinx or MkDocs to build the files locally through the command line, rather than using a commercial program.
• Working with files using a text editor that supports docs-as-code, such as Visual Studio Code.
• Keeping track of the documentation in a version control repository (usually a Git repo), similar to how developers store programming code, rather than keeping docs in another space like Dropbox or a SharePoint drive. Additionally, you can store the docs in the same repository as the code itself.
• Working with other writers using version control systems such as Git to track changes in the plain text files instead of collaborating through large content management systems or SharePoint-like check-in/check-out sites.
• Automating the site build process with continuous delivery to build the documentation website when you update the repository, rather than manually publishing and transferring files from one place to another.
• Executing validation scripts to check for broken links, improper terms/styles, and formatting errors instead of spot-checking the content manually.
• Managing docs using processes similar to engineers (e.g., agile scrum), such as dividing documentation tasks in an issue manager (such as JIRA), allocating the issues to bi-weekly sprints, and informing stakeholders about the tasks finished (showing demos).

Tools used in Docs-as-Code

There are many tools that you can use with the Docs-as-Code approach. They include:

• Plain text markup such as reStructuredText or Markdown. We recommend you use reStructuredText. You can read this article first to help decide which markup language to use in your project.
• Static site generators like Sphinx.
• Text editors that support Docs-as-Code, such as Visual Studio Code.
• Git for version control and GitHub for storing remote versions of the repository.
• Continuous integration and continuous delivery tools like GitHub Actions.
• The Python programming language.

The Benefits and Limitations of Docs-as-Code

Using the docs-as-code approach has both merits and demerits, which you must consider before adopting it into your project. Below are some benefits and limitations of using the docs-as-code approach.

Benefits

• Collaboration with developers: The docs-as-code approach improves collaborative efforts between developers and technical writers, enabling the provision of better and more accurate documentation. Often, writing documentation for a particular product is complex enough to necessitate involvement from developers for both writing and reviewing. As a result, implementing the docs-as-code approach encourages developers to contribute to the product documentation, allowing technical writers to focus on documenting how to use the product effectively.

• Integration with other infrastructures: You can incorporate the docs-as-code workflow into existing company or project infrastructures. Most companies rely on certain infrastructures to operate, and any new approach they adopt must integrate seamlessly with those existing infrastructures. The docs-as-code approach is suitable for such companies because of its flexibility, making it easy to integrate into any existing infrastructure. For example, useblocks GmbH, a German software solution company, has developed a Sphinx-Needs Enterprise plugin that integrates Sphinx-Needs into company-specific tool environments. This synchronization of data between Sphinx-Needs and existing tools like Jira, Azure, GitHub, and CodeBeamer ensures the utilization of data from other existing tools with Sphinx-Needs, resulting in the generation of meaningful documentation.

• Contribution from the open-source community: The docs-as-code approach embraces external contributions from other technical writers, subject-matter experts, and users. While not all documentation projects are public, most allow other contributors to participate in their development, aiding in the discovery and resolution of issues in the documentation. Although these contributions need to be reviewed to ensure they align with your style guide and content strategy, the input provided by the community helps enhance your documentation.

• Continuous Delivery: In the docs-as-code approach, you can rebuild your output by simply committing and pushing content into a Git repository. The repository will detect the changes and trigger a build and publishing job, a process known as Continuous Delivery. You can edit multiple pages and send your changes to your production repository. When the changes reach your production repository, an automatic content build and deploy process runs on your repo, quickly transferring the output files to your server. You no longer need to FTP files to a server or follow a manual deployment process. A quick update and a Git commit are all you need to change your documentation. This helps reduce the pressure of publishing and deploying docs and also encourages developers to write and contribute to the documentation. Continuous delivery is the feature that makes docs-as-code so much more effortless (with publishing) compared to other solutions.

• Delivery of updated and validated documentation: Using the DaC approach, you can deliver up-to-date documentation to your users, enabling them to access accurate content. For example, most Sphinx documentation sites provide information about the date of the last changes. This information informs readers if they are reading outdated content or not. Additionally, we can use validation scripts in our docs-as-code approach to ensure we validate each content before publishing it. Validation scripts, such as checking broken links or verifying if the content meets the style guide, help us identify mistakes so we can correct them.

• Integration with A.I. tools: You can use A.I. tools to assist in drafting and reviewing documentation, enhance documentation search capabilities with tools like Algolia DocSearch and TypeSense DocSearch, and provide a support assistant chatbot like DocsBot AI that helps software users access information and troubleshoot problems.

• Content reuse: Content reuse is the ability to include content from one document in another. Most docs-as-code static site generators support content utilization using templating languages like Jinja to enable documentation writers to use conditional filtering, content reuse, variables, and more when writing documentation.

Limitations

Here's the revised version with corrections:

The following are some limitations of docs-as-code:

• Learning Curve: The DaC approach requires writers to be familiar with software development tools like Git. Additionally, most technical writers use Markdown to write their documentation. Although the Markdown language is easy to learn and use, it lacks standards. The many flavours of Markdown syntax make it challenging to use the same Markdown text across all Markdown-supported static site generators.

Note

Instead of using the Markdown language, we recommend you use the reStructuredText language.

• Tool Integration: Integrating documentation tools into existing workflows can be tricky at times if best practices are not implemented.

• Cultural Shifts: Both technical writers and developers must agree to the use of this approach for successful implementation.

• Localization: Localization in docs means adapting your documentation to the needs of a particular language. Having your documentation in multiple languages is a requirement for a documentation site that aims to convey its message to a particular language and culture. Most docs-as-code static site generators do not support translation (except Sphinx). While we write most technical documentation in one language, it is appropriate if these docs-as-code tools support localization.

• Hard to prevent Git disasters in public technical documentation: Using version control systems, like Git in the docs-as-code workflow, requires some training and a code of conduct to prevent Git mistakes in public documentation.

• No PDFs: For most technical documentation, it is necessary to generate PDF documents for the entire documentation project or single pages in the documentation. PDF is possible, just not usually an out-of-the-box feature.

Note

You can try out either the Sphinx-PDF Generate or the Sphinx-SimplePDF plugin if you are using Sphinx-Doc.

Conclusions

In most companies, technical writers adopt the docs-as-code approach to write both external and internal technical documentation. Although there are challenges with the approach, if the right measures and practices are put in place, both the developers and technical writers will benefit hugely from adopting the docs-as-code approach to document up-to-date content for their software users.

Below are some best practices I would recommend if you want to adopt the docs-as-code approach in your projects:

• Early Integration: Integrate the DaC approach into your documentation project early in the development process.
• Automated Testing: Employ automated testing tools like PyTest, linters, and formatters in CI/CD tools like GitHub Actions to ensure documentation accuracy.
• Consistent Formats: Analyze and select one or more text-based formats to use in your project and provide standards on the text-based formats choosen for ease of collaboration.
• Use third-party software and collaborative tools: Utilize third-party tools to ensure writers focus on writing and delivering documentation quickly and to ensure collaborative editing and review.
• Additionally, create a docs-as-code ecosystem that is open to all contributors. If users contribute to the documentation, it enables a workflow where writers and users feel ownership of documentation and work together to deliver essential information.

There is more to building a proper Docs-as-Code ecosystem, and I hope to find and share such knowledge with everyone.

Kindly comment📝, like👍, and share🔗 this article if you find it informative.