What is Docs-as-Code?

The Docs-as-Code (DaC) approach to writing documentation has been gaining popularity in the last few years. Although it's a relatively new term, people have been using DaC-style workflows for almost as long as computers have existed. They just didn't call it "Docs-as-Code." The fact that lots of people have now heard the term is a testament to how many more people (and companies) are using the DaC workflow.

To be clear, parts of this post will be my opinions about DaC. I've used some form of DaC for my entire career in the software industry, most recently as a Technical Writer. While it's true that some people raise objections to the DaC workflow, I find it telling that DaC is used both by startups and the largest software companies in the world. For example, Meta, LangChain.com, Python’s official documentation, Django docs, and Apache.org all use DaC.


As with any approach, DaC has its own set of advantages and disadvantages. In this post, I’ll define the DaC workflow and explore why I continue to choose to adopt it. For me, the flexibility and the potential for automation outweigh the challenges, especially when paired with Git-based version control and the ability to script around its disadvantages. But first, what exactly is Docs-as-Code?

What is the Docs-as-Code workflow?

In simple terms, a Docs-as-Code workflow treats documentation the same way as software code. It employs version control, automation, and code-based tools to streamline the creation, management, and deployment of documentation. Docs-as-Code can enhance collaboration and automation—core principles familiar to software development teams.

In other words, Docs-as-Code refers to writing, editing, and maintaining documentation using the same (or similar) tools and processes that developers use for coding. Documentation is written in plain text formats, often in Markdown, stored in a version control system (such as Git), and usually published using a static site rendering (SSR) tool such as Sphinx, Docsify, Slate, MkDocs, Docute, VuePress, or Docusaurus. This workflow mimics the coding lifecycle: documents are written, reviewed, versioned, and updated with the same rigor as code.

The process typically includes:
  • Version control: Just like with code, changes to documentation are tracked through Git or another versioning system. This means documentation has a history of changes and allows for better collaboration.
  • Automation: Tools such as continuous integration (CI) pipelines can be set up to automatically build and publish documentation, ensuring that it is always up-to-date and accessible.
  • Collaboration: Writers and developers collaborate on documentation in much the same way they collaborate on code, with pull requests, code reviews, and comments.
  • Reusability: Documentation can be modular and reusable, just like well-structured code. This allows for consistency across projects and reduces redundancy.
It’s key to remember that the Docs-as-Code workflow does not depend on any particular tools. Just like Scrum is not Agile, the various tools used for DaC are just implementations of the workflow. Futhermore, whether they are proprietary or open-source, the tools used in the DaC workflow can be swapped in and out to meet a particular organization’s requirements. While one team might choose to edit their docs with Visual Studio Code, another team (or even members of the same team) might choose to use the Sublime Text editor, or Cursor instead.

Disadvantages of Docs-as-Code

I'm biased since I'm a DaC fan, but I'll try to be objective in this section. For writers without a strong technical background, Docs-as-Code can be intimidating. Some disadvantages include:

• Initial learning curve: Tools like Git, CI pipelines, and scripting languages are powerful but can be difficult to learn for those without prior coding experience. Writers may find themselves needing to learn additional skills before being able to fully participate in this workflow.

• Technical overhead: Setting up a Docs-as-Code pipeline requires familiarity with version control systems, build tools and automation scripts. For a small team, the initial setup can feel like overkill, especially when maintaining simple documents.

• Collaboration challenges: Although Docs-as-Code can facilitate better collaboration with developers, it can also create silos if writers feel excluded because the collaboration doesn't happen in tools such as Google Docs.

• Lack of WYSIWYG tools: Writers accustomed to rich-text editors such as Microsoft Word or Google Docs might find it frustrating to write in Markdown, reStructureText, or other plain-text formats. While some editors (such as VSCode) provide a WYSIWYG experience for Markdown (or other mackup languages), they may not be as familiar or feature-rich as other options.

Advantages of Docs-as-Code

Despite these drawbacks, Docs-as-Code comes with several significant advantages, especially for teams working on complex, fast-moving software projects. Whether it's for my own side projects or for companies such as Twitter and Microsoft, I've always favored DaC over other documentation workflow options.

  • Version control and collaboration: Treating documentation as code makes it easy to track changes, assign responsibility, and roll back to previous versions. This is crucial for maintaining a clear history of what was changed and why. Pull requests also make it easier to propose updates and ensure that they are peer-reviewed before being merged.
  • Automation: Docs-as-Code integrates seamlessly with CI/CD pipelines. Every time a change is made, the documentation can be automatically built, checked for errors, and published without manual intervention. This level of automation provides benefits that simply aren't available in non-DaC workflows.
  • Consistency and standardization: Writing in Markdown or other plain-text formats ensures a consistent style across all documentation. Templates and reusable content blocks can be created to ensure that certain types of content, such as API documentation, follow the same structure across multiple projects.
  • Collaboration with developers: Developers are already familiar with Git and coding workflows, so Docs-as-Code allows them to contribute directly to the documentation without learning new tools. It also reduces the friction between documentation and code, as changes to both can be made simultaneously.
  • Security: Docs-as-Code benefits from the same security and backup processes that developers rely on, as all documentation is stored in the same version control system as the code.
  • Scripting and customization: One of the biggest advantages for me personally is the scriptability of Docs-as-Code. Whether it’s automating repetitive tasks, generating content dynamically, or building custom pipelines to suit specific needs, the flexibility this workflow provides is unmatched.

Why I chose Docs-as-Code

I think this section is actually worthy of its own post; however, until I have that published, I'll provide a short answer here. I believe that the issues people raise with DaC can be quickly overcome after using the workflow and getting used to the tools and processes involved. These are the primary reasons that I chose Docs-as-Code:

  • Flexibility: The flexibility to control every aspect of the documentation workflow is incredibly powerful. As a Technical Writer who enjoys automation and efficiency, Docs-as-Code allows me to streamline processes that would be tedious with traditional documentation tools. I can customize my environment, integrate new tools, and adapt to changes quickly without being tied to a proprietary software solution.
  • Scriptability to overcome disadvantages: While the learning curve for Git, Markdown, and CI pipelines may be steep for some, I found the ability to script around common problems incredibly useful. I’ve written custom scripts to help automate formatting checks, broken link detection, and other tasks that would otherwise take hours. With these scripts, Docs-as-Code becomes a highly efficient, low-overhead workflow that scales well as your documentation needs grow. For instance, when dealing with frequently changing documentation, automation scripts can easily highlight differences between versions or automatically update sections based on new code. This level of automation makes it easier to manage large documentation sets without losing track of crucial changes.
  • Git-based workflow: Perhaps the strongest reason for adopting Docs-as-Code is the integration with Git. By using Git for documentation, every change is tracked, versioned, and tied to specific branches or pull requests. This integration also simplifies collaboration between writers and developers, as they can use the same workflow to propose changes, review content, and ensure consistency between code and documentation. Git-based workflows also enable powerful branching and merging strategies, allowing multiple writers to work on different parts of the documentation simultaneously without conflicting with each other. Merges can happen seamlessly, and conflicts can be resolved with the same tools developers already used to handle code changes.

Conclusion

For everyone working on documentation who values flexibility, automation, and collaboration, Docs-as-Code offers significant advantages over traditional methods. By treating documentation like code, it becomes easier to version, review, and automate, ultimately improving both the quality and consistency of the documentation.

For me, DaC's flexibility and scriptability are key. While the lack of familiar tools can be a short term challenge to new users, the ability to automate tasks and integrate directly with the development workflow makes it worthwhile. Git-based version control ensures that documentation stays in sync with the code, allowing for a streamlined process that grows with the project.

Ultimately, Docs-as-Code offers a future-proof way of handling documentation that can scale with your team’s needs. Whether you’re part of a small team or working on large, complex projects, the ability to script around challenges and automate repetitive tasks is invaluable.

Written by: Stephen Cawood

Comments

Post a Comment

Popular posts from this blog

Is AI useful to Technical Writers?

Image
Since the head-spinning rise of ChatGPT , most people simply refer to the current crop of generative AI large language models (LLMs) as "AI." LLMs are powerful systems trained on extensive data and have opened new avenues in many fields, including journalism, creative writing, coding, and even visual design. However, when it comes to writing documentation, their use continues to be complex and nuanced. While generative AI is immensely helpful in some areas, it faces critical challenges in others, particularly due to its inability to validate the truth of its own outputs. In this post, I’ll explore the specific strengths and limitations of LLMs in the domain of technical writing and some best practices for using them effectively. I should also say up front that I'm currently employed as a Technical Writer, so I have some understandable biases when it comes to this subject. However, I am definitely not in the camp of people who dismiss AI outright. In fact, I'm currentl...
Read more

You're technical enough to use Docs-as-Code

Image
During my interview for my last Technical Writer position, I was asked, “Do you have any experience with Docs-as-Code ?” The company used it as its documentation solution, so it would’ve been nice if I had used it before. I had not. In fact, I had never heard of it. Apparently, I was charming enough to get the gig anyway, but I was nervous about my ability to learn the workflow quickly despite having been a Technical Writer for two years at that point. It turned out my concerns were unfounded, and not only did I flourish using Docs-as-Code, but for the past year and a half, I have made it my preferred documentation option. If you find yourself unsure of having enough technical prowess to wrap your head around Docs-as-Code, I will reassure you with this: if you’re the type of person who would peruse a page on this subject, you’re more than qualified to use Docs-as-Code. You’re inherently somewhat technical Chances are, since you’re here, you have some interest in what’s discussed on thi...
Read more