Posted on April 25, 2022

Guest post originally published on Mia-Platform’s blog

Introduction

In the lifecycle of a software product, documentation plays a very significant role: without it, users struggle to use the software, or, in the best scenario, they do not take advantage of its full potential. The most tenacious users may, in fact, get to work with the most intuitive features, but are unlikely to discover the more complex properties, which usually are the most valuable ones of the software. Even if users succeed in this challenge, they usually take a long time with tiring procedures, a poor user experience, and this will eventually make them look for an alternative provider.

Producing comprehensive and easily accessible documentation avoids this worst‑case scenario. If users can easily and intuitively find the information they need and know that it will be thorough and understandable, they will enjoy a better experience and take full advantage of the software. However, quality documentation requires a significant commitment of time and resources. Often, big companies will hire specialists, such as Technical Writers, who are full‑time dedicated to producing and updating documentation. On the other hand, in small/medium‑sized companies that cannot afford such an investment, writing documentation is one of the development team’s jobs. In most cases, developers prefer to focus on their core business of software development instead of writing and updating documentation. This is also because the tools used for writing are very different from those that developers normally use for their daily activities.

To reduce these kinds of problems and to meet the needs of developers, over the years the Docs as Code (or Docs like Code) approach was born. In this article, we’ll look at the pillars of this approach and the main benefits it brings, while also showing how we adopted it within Mia‑Platform.

What is the Docs as Code approach?

The idea behind this approach is to treat documentation as an intrinsic part of the software source code, and therefore it should be written and updated with the same tools and procedures that developers use on a daily basis for coding‑related activities. Actually, this approach is a radical shift in perspective that puts the Developer Experience at the center. Instead of trying to force developers to use the tools and methodologies of a technical writer, with this approach, it’s the documentation that is adapted to the tools and habits of the development teams. 

It is important to note that this approach is not limited to adopting developers’ tools, but it also embraces all their processes and working methodologies: in particular, it allows you to work in Agile.

How Docs as Code works

Let’s now delve into how the Docs as Code approach works in practice, showing the tools to adopt and the processes to put in place to implement it within your company.

Plain text

The most widely used tool by development teams is surely the IDE (Integrated Development Environment), so it is important that developers continue to use it for writing documentation. For this reason, documentation should be written to files in a plain text format, which can be read and edited directly from the IDE. In this way, developers will be able to browse the code within the same program used for writing the documentation of the code itself. Using a single tool avoids, or at least reduces to a minimum, a dangerous switch of context that could distract and slow down developers.

Plain text formats are compatible with all IDEs used by developers, but they can also be easily read by other people that are not familiar with IDEs. Almost all operating systems have natively integrated programs that let you read these kinds of files. In addition, there are many free and open‑source tools online that are easy to use even by non‑technical people. 

Another important advantage of this type of file is that it helps developers to focus on technical content: the team in charge of writing the documentation will not have to worry about its layout. Usually, plain text formats are mainly used to write commands for machines, such as configuration files. However, since the documentation is intended to be read by a human audience, it is advisable to adopt a plain text format that allows using basic formatting. The main formatting features required for a technical paper are:

By taking advantage of these simple features, the readability of the content will be significantly improved, while at the same time, the writing experience will not be overly burdening.

Versioning

Once the file type and the text editor have been defined, another fundamental aspect of the Docs as Code approach concerns documentation versioning: it is essential to keep track of all changes, knowing by whom they were made and when. The development team is already familiar with this way of working since it is a well‑established and widespread practice to use a version control system (VCS) to monitor and track their software code: so, in order not to interrupt their workflow when developers need to write documentation, it is then just a matter of adopting the same VCS that they use for code.

Some of the most popular and free VCSs include Git, Mercurial, and Subversion. However, instead of adopting one of these VCSs directly, almost all companies rely on hosting platforms that leverage one of these systems while offering additional functionalities. Git has had a great fortune and considerable diffusion thanks to its relative ease of use, and because it is open source. As a matter of fact, the most worldwide known and used platforms, namely GitHub and GitLab, are based on Git.

According to the Docs as Code approach, documentation should be saved within the versioning tool that is already adopted in the company for the source code. You can decide to keep the documentation within a single repository dedicated to it, or you can choose to distribute it, i.e. keep the documentation of specific functionality in the same repository where the code for that functionality is stored. These are implementation details that can vary depending on many factors: the important thing is that all files are stored and versioned within the same tool used for the source code.

In addition to versioning, adopting GitHub, GitLab, or an alternative platform fosters collaboration among developers. Thanks to Pull Request (also called Merge Request; depending on the platform, the name of the action changes, but the operation is the same), everyone can suggest changes to the documentation without the risk of affecting the original file. In addition, these features let you see precisely what changes have been made to each file, and there is a dedicated space to discuss and explain each change. The team responsible for documentation can then make fine-grained decisions about which changes to accept and which to reject.

Another great advantage offered by these tools is the possibility of working asynchronously with several people on the same file. Thanks to branches, anyone can create a version of the files on their device, make changes, and then create a Pull/Merge Request to have the changes implemented. All this without directly affecting the original file or the other people who are working on other versions of the same file. The platforms also provide an interface to easily report and resolve conflicts (i.e., two different, competing edits to the same section of a file).

Publishing

Once the documentation has been written, versioned, and saved, it is ready to be published. The best way to publish files in plain text format, which already has basic formatting, is to create static web pages, using a static‑site generator (SSG). An SSG easily transforms plain text files into HTML, allows you to add CSS stylesheets to enhance and brand the look and feel, and, if needed, lets you add dynamic JavaScript sections as well: everything will then be rendered server‑side, providing the client with static pages that are very fast to load.

Thanks to an SSG, you can easily decouple the content and its final graphical representation: the development team will be responsible only for the technical content, while responsibility for the visual aspect may be given to another team. This way, developers don’t have to worry about selecting the correct font, formatting the content, or any other such activity: they will only care about adding the basic formatting directly into the plain text file. Besides, in this way any graphic change can be cascaded to all pages, editing just one style sheet.

Most SSGs also offer several additional features that greatly enhance the usability of the content, but do not necessarily require manual intervention by the development team. Examples of these additional features include:

These features are pretty simple in their own right, but together they make it easy to find and consume content, helping users to quickly find what they’re looking for.

Automation

An additional benefit of the Docs as Code approach is the ability to leverage automation that is usually implemented for source code: in particular, thanks to this approach it is possible to introduce typical elements of the DevOps world, such as CI/CD (Continuous Integration and Continuous Delivery) practices. 

Concerning CI, you can create automated tests that check the content each time a Pull/Merge Request is made on the main branch: such tests can detect technical errors (i.e., invalid links, invalid code snippets, etc.) or formal errors (i.e., typos, missing punctuation, etc.) within the documentation. If the tests fail, the team is notified of the error and can take action to resolve it; if the tests pass, the CD phase can begin.

As an example of how you can leverage CD, you will be able to create automation that detects all changes within the main branch, and automatically the new content is published. This way, you won’t have to spend time on the publishing process, which traditionally takes a lot of time.

Depending on your needs, you may decide to implement only one of the two practices, but adopting both will ensure that you speed up many procedures and avoid errors in production.

How we implemented Docs as Code within Mia‑Platform

Let’s now see in more detail what tools and methodologies we have adopted in Mia‑Platform to implement the Docs as a code approach.

As for the plain text format of the files, we opted for Markdown. It is a markup language that is very easy to learn and use, and allows you to handle all the main basic formatting functions. It is also one of the world’s most popular languages among developers, which is why most IDEs provide a wide range of add‑ons to improve formatting visibility even within the IDEs themselves. This allows you to have a preview of the result already at the writing stage, thus helping the team to see any errors right within the editor. Regarding the IDE, as we said, there are no particular indications, and everyone is free to use the tool with which they are most familiar.

For versioning, we chose the same Git‑based platform we use for code management, i. e. GitLab: we chose it because it is open source, and it also provides some useful DevOps tools. For simplicity, we created a dedicated repository that stores the documentation for all artifacts. Everyone within the company has access to this repository and is not only free to access it, but encouraged to contribute: it is basically a transposition of the Open Source contribution methodology, but limited to company employees. 

In addition, GitLab has allowed us to implement some CD automation: for example, any change on the main branch triggers a pipeline that publishes the documentation to a test environment, where you can preview the final result.

The choice of SSG has fallen on Docusaurus, an open‑source tool designed specifically for software documentation. The peculiarity of this SSG is that it creates single‑page applications instead of simple static pages, and it takes advantage of the potential of React to make the site interactive. Thanks to these features it is possible to create very graphically advanced sites.

Main benefits of Docs as Code

Adopting the Docs as Code approach brings several benefits, both for the users of the documentation ‑ who are often customers outside the organization ‑ and for those within the company who are in charge of writing it. Starting from the external use, contents will be simple and quick to find thanks to the ease of use of the site: this allows users to quickly learn how to use the software correctly, and to quickly solve any problems. 

The biggest benefits, however, occur in the writing process. Let’s see below what they are:

In conclusion, the Docs as Code approach adapts documentation writing to the tools and processes already used by developers for writing code. In this way it significantly contributes to providing a better Developer Experience, improving developer productivity, and increasing quality of the documentation.