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.
TABLE OF CONTENTS
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 flavors 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 selected 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.
Top comments (13)
As for tools integration, is just a matter of finding one. I saw that problem when I started to work on my personal blog and decided to create a "bridge" for people who are a bit less tech savvy that connects MkDocs with Obsidian.md (both are using Markdown files). This way you can have a great editor that helps a lot with text formatting and cross documents linking and probably one of the best building and presentation side (especially with Material for MkDocs). If you are interested in my project take a look at MkDocs Publisher.
Will definitely check out MkDocs Publisher. Thank you.
Java JEP 467: Markdown Documentation Comments" uses my original method on 2019-02-17
Markdown Literate programming that don't break the syntax of any programming language
Live preview in Notepad++
Also diagrams as code - packagemain.tech/p/software-archit...
I agree 💯. With Docs-as-Code you are able to convert plantuml, graphviz, mermaid or drawio codes into diagrams that help you to add more details to your documentation.
Well written post
Thank you 🫡
I love how rust has cargo doc which supports this sort of stuff natively.
Very well complied!
Thank you 🫡
Very nice read 🔥
We are currently using Vue for our application and I think with this approach we could use something like VitePress to generate docs as webpages for markdown documented requirements. That way the actual functionality/code is closely coupled to the requirements documentation and testers/stakeholders can review these for testing/understanding.
However, i'm not sure about other documentation that isnt directly connected to the current version of your code. There a system that just allows for quick editing and saving could be more beneficial. What do you think?
But at the end it really depends on the team size, experiences, use cases, project management, ...
If VitePress supports versioning then it will help to have your other documentations linked to your current version so that stakeholders can choose which version of the documentation to use based on the code version.
You can also checkout MkDocs and Material for MkDocsto see if it matches your use case.
Yea, I think for our use case simply linking is more than enough. MKDocs seems nice but I think we got more flexibility with VuePress since we are using Vue already so its not something new to learn or another technical workflow to add to the stack.
But really nice post, I'll definitely come back to this in the future.