What Are The Advantages of Docs as a Code Approach
Published on • 6 minutes readCreating a project wiki is the most popular option for software projects. This approach has its own advantages. Documentation can be easily accessed by non-technical teams - like product and business teams.
Before we decide on the tool for documentation based on this advantage, we should ask ourselves a question.
Is it important for such teams to read strictly technical documentation explaining concepts and decisions about the codebase?
Google Case Study #
That was the case for Google. All the documentation was on the wiki. When the documentation started growing, parts of it became obsolete and it wasn’t properly maintained. Some documents were duplicated and it caused even more chaos.
Another problem was sharing feedback. There was no easy way to report errors in the documentation.
Documentation started to be so bad, that it was the number one developer complaint on the annual developer survey.
The solution for Google was to start approaching docs as a code. All the documentation was moved under the source control. When developers started using familiar tools, it allowed them to resolve most of the problems.
8 Advantages of Docs as a Code Approach #
There are numerous advantages of storing code-specific documentation close to the code. The main one is using all the tools which are already used by the team, which means that there is no need to teach how to use new tools. There are also advantages of making documentation more connected to the code, so it is easier to understand.
1. You Can Easily Track Changes #
The main advantage of treating docs as a code is tracking code changes. If you leverage source control for that, you can see the authors of the changes and the point in time when they were made. It is way easier to check the history of the document and you can even see the corresponding changes in the code if documentation was included in the Pull Request.
2. You Can Leverage the Existing Code Review Process #
Review documentation like the code. You do not need any other process for that, because documentation will be reviewed through Pull Requests. That is very convenient for the developers.
3. You Can Effortlessly Track and Report Issues #
Having documentation under source control brings also another benefit. It is easier to report issues and track them. It is important to make it easy to share feedback, so it is easier to spot issues and maintain documentation.
4. You Can Easily Find Files Under the Source Tree #
Files are in the source tree, so it is easier to find them, and it is more intuitive when placing new files. You can also verify if the part of documentation was already created, so you avoid duplicating it.
5. You Can Simplify Workflow Thanks To Markdown #
Another advantage might be simplicity. It is way easier to learn and use tools such as Markdown instead of using HTML and CSS or learning some other documentation tool. Reducing the complexity of writing documentation is important to help the team write.
6. You Can Assign Owners To The Documentation #
On top of the ability to see who has changed the document, you can also assign the owner of the documentation. You can add that information as a comment in the file so it is clear who is responsible for maintaining it. You can also leverage tools to make this person a main reviewer of changes to those files.
7. You Can Leverage Automated Pipelines #
Keeping docs close to code allows leveraging automated pipelines. Some tools allow for checking links or images before the documentation is published. You can also prevent people from merging some PRs if the documentation is not included. There is also a possibility to set up a linter, which tests documentation. You can validate things like proper file names, enforce headers or verify spelling.
8. You Can Create Dynamic Diagrams #
If you store documentation in the codebase, you can use tools such as Mermaid.JS, that allows rendering diagrams dynamically.
Instead of using an external tool, managing accesses, and making sure that diagram is up to date, you can create them with code. You can then store code in the repository and automatically rerender the diagrams before they are displayed.
If you use Github, Mermaid.JS is built-in and automatically rendered, so you do not need to install additional tools.
Is It Possible To Have Both Docs As Code And Render Documentation Pages? #
There are tools that enable the creation and storage of documentation in the codebase while also enabling searching, and reading through web pages. That is also the approach that Google took with their g3doc tool.
There is a variety of tools, which allow you to store documentation in the repository, and display it formatted in your web browser. You can use tools for static site rendering, but you can also choose documentation generators or synchronize docs to the tool of your choice.
Static Site Rendering Tools #
You can use tools that render documentation websites, which can be easily searched, displayed with all the links, and with easy to use file tree. All of that is generated out of your markdown files. Tools like Docusaurus or Backstage allow you to do it quite easily with minimal setup. To see the example of documentation created with Docusaurus, take a look at the sticky parallax header open source library.
Documentation Generators #
Documentation Generators create reference documentation out of the comments in your code. It is a great tool to document your API. There are options for most programming languages, and examples are TSDoc or JavaDoc. If you build apps for Apple platforms, you can check Swift-DocC which does a great job of creating the interface for your documentation.
Git Synchronisation #
You can also sync your markdown files from the repository and use tools such as Notion, GitBook, or ReadMe. It will process your files and render them, so they are easily accessible by every team member.
GitHub Wiki #
This tool is great for creating Wiki for your project, especially if it is an open-source project. It renders documentation in your repository GitHub Page. It is also using Markdown. Unfortunately, it is not allowing you to use all the advantages of docs as a code. When enabling GitHub Wiki for the first time, it creates a separate repository. It means that you cannot change wiki content with your regular pull requests.
The solution for that is storing documentation in the main repository and then syncing files through GitHub Actions, so it is available to read in GitHub Wiki.
GitHub Wiki is available in public repositories or if you have a paid plan. It is not a free tool for private projects.
Summary #
Documentation is usually hard to create and maintain, but it comes with multiple advantages. Some of the issues can be mitigated by treating docs as code. Developers prefer to use familiar tools to maintain documentation. Following the example of Google you can also successfully leverage them in your team. There are many tools that need almost no setup and support storing documentation in your repository while allowing everyone in your organization to read them.
What is Your Experience with Docs as Code Approach? #
Let me know your thoughts on Threads - @this.dev or Twitter - @IdaszakDaniel.
Tweet