Unlocking Efficiency and Collaboration with Docs-as-Code

In the world of software development, Docs-as-Code is the practice of managing, writing, and updating documentation using the same tools and methodologies as software development. Inspired by Joanna Suau’s insightful presentation at the Infobip Shift Conference on “Why Docs-as-Code Peer Review Should be Part of your Dev Cycle“, we will try to explain to you how to leverage this approach, the upsides of it, and how to seamlessly implement it in your development cycle.

So what is Docs-as-Code exactly? It is a mindset shift that treats documentation as code, applying version control, collaboration, automation, and testing to ensure that documentation remains accurate, up-to-date, and easily accessible.

A mouthful of fancy-sounding words, right? Let’s simplify it down to what is really important to note here and create an example together.

What is “Docs-as-Code”?

The very simple idea behind this concept is to create, write and update your documentation the same way you create, write and update your code. This is achieved by keeping your documentation in version control systems, alongside your codebase. It is often stored in formats like Markdown or reStructuredText to be able to render it nicely with less effort. Having your documentation files in the code repository means that the changes to documentation can be tracked, reviewed and merged the same way as code changes.

So, you’ve got this Docs-as-Code idea in your head, but what does it look like in the real world? Let’s get down to brass tacks with a few examples you’re probably familiar with:

1. README.md:

Docs-as-Code “hidden” in plain sight. You likely use the README.md file in your repository. It can range from simple instructions on how to get your project up and running – but it can also dive into technical details if needed.

2. Swagger and API Endpoint Documentation:

API documentation is extremely important. If you’ve ever used Swagger or a similar tool to document your API endpoints, you’re already embracing Docs-as-Code. Keeping that documentation current and documenting the changes is like having an up-to-date map of your API for your colleagues. 

Chances are, you’ve encountered these Docs-as-Code practices, or perhaps you’re already using them without maybe even realising it.

The Upside of Docs-as-Code

One of the standout advantages of Docs-as-Code lies in its ability to enhance collaboration within development teams. Centralizing documentation in a single accessible location streamlines the onboarding process for new team members and provides valuable insights for “future cases of amnesia”. 

Embracing Docs-as-Code means treating the documentation with the same diligence as the code itself. Rather than treating it as a separate entity, it becomes an integral part of the development process, sharing the same tools and workflows – hence the phrase “Keep the docs close to the code“. The tight-knit relationship of documentation and code in the Docs-as-Code approach makes you more encouraged to work on the documentation, leading to more up-to-date docs.

At the core of this integration is Git, a well-established version control system. Git provides a robust framework for tracking changes, managing collaboration, and maintaining a clear history of your documentation. When you combine an examination of the documentation with a review of the code itself, the likelihood of making errors is significantly reduced. Following this process enables your team members to proofread and suggest changes, as there may be some typos and parts you accidentally missed. This often leads to discussions that result in a unanimous decision on the best course of action.

Below, you’ll find concrete examples from our merge request comments:

Now, after delving into the world of Docs-as-Code and its advantages, traditional methods might start to lose their sheen, right? In the past, tools like word processors, Google Docs, PDFs, and Confluence were the go-to choices. Yet, they often painted a picture of static, unwieldy documents, resistant to change, and not exactly best buddies with modern development workflows. For us, the Docs-as-code approach helped us to avoid the common pitfall of forgetting to document essential information since it is something that should be an integral part of your development process, not an afterthought.If you’re still uncertain about the benefits of this approach, allow us to share a scenario that motivated us to enhance our documentation practices. We were working on a feature when other priorities suddenly demanded our attention, forcing us to temporarily halt its development. Fast forward a year, and we resumed work on the same feature, only to find ourselves spending time reacquainting ourselves with the code. This situation could have been easily prevented if we had kept thorough documentation, significantly reducing the time spent on recalling the details. That’s why we embraced this practice in our day-to-day workflow.

Getting Started with Docs-as-Code

So, if you’ve found yourself intrigued by Docs-as-Code and are ready to jump in, let’s explore what steps you should take to get started. We have also created a step-by-step guide for you on our GitHub in case you want to try it out later.

If you’ve got a public repository, the easiest and quickest way to create a Docs-as-Code environment is by using your GitHub repository’s documentation feature to document your code. Inside your repository, you can create links to different markdown files, creating a well-organized documentation system.

But in many cases, you might not have a public repository, or you might want a more advanced documentation setup on a web page. Luckily, with today’s tools, this isn’t too complicated (and you can try it out for free).

Required components to get started:

Git repository: You need a git repository where your code and documentation will be hosted and version controlled

Hosting platform: A platform your repository will be hosted at (GitLab, GitHub, BitBucket, etc.)

Documentation Generator: Select a documentation generator from the variety of the available ones. This tool will be responsible for transforming your markdown files into a website.

For a simple documentation, consider MkDocs or Sphinx

If you require more flexibility and a very customizable interface for your documentation you can check out Docusaurus 2

A hosting service: To deploy your documentation site, you will need a hosting service

In case you are using MkDocs or Sphinx, the best options are likely ReadTheDocs or GitHub Pages

If you are using Docusaurus 2, or something similar, it might be worth checking out Netlify or Vercel

Self-hosting is always an option

Finally, after choosing your set of tools and setting everything up you should have a simple system that looks like this:

Once you choose your set of tools for this job it is time to configure the documentation structure. The organization of the documentation is essential for clarity and accessibility. It provides a roadmap for users and developers, making it easy to find and understand information. A well-structured documentation system encourages and eases collaboration which is the main aim of documentation.

As mentioned earlier, we created a short and simple demo for you on our GitHub. You can follow the exact steps in the README.md file to replicate the minimal project on your side.

Navigating the adoption process

One of the most common challenges encountered when transitioning from traditional documentation to a modern Docs-as-Code approach is resistance to change. This resistance often comes from individuals within your organization who are accustomed to the old ways of documenting.

We know it can be hard to get going and change the process you are familiar with, but you have to think of the long-term benefits you will gain by switching to this style of working. We won’t lie – it is still not our favourite job to do. 

But, once we adopted this approach, we witnessed lots of improvements. Our documentation writing became more consistent and it simplified the onboarding process for new team members. It also led to fewer inquiries from our QA and other teams about specific feature functionalities. Perhaps most importantly, we decreased moments like this when revisiting sections of code we had written:

Now, let us share some guidelines for how to make the transition to Docs-as-Code smoother so you can enjoy long-lasting benefits from this change:

And there you have it – Docs-as-Code. Always keep in mind that the most challenging part is getting started. We encourage you to take the first step towards the many possibilities of this approach.

Happy coding and documenting!