Few things are as important to the longevity and success of a system as the documentation that underpins it. Developer experience hinges on documentation, the quality of which can often make or break the solution in the long run. How a team implements this documentation, then, should be seen to be just as important as the code itself.

To that end, various strategies, mindsets, and paradigms have been adopted to help guide the development and implementation of cohesive documentation systems. One such paradigm, Documentation as Code (Docs as Code), is a strong approach for many teams seeking to unify their documentation and development efforts. In this piece, we’ll look at what Docs as Code means, what it does, and how to best implement it, as well as at some standard tools and specifications that can help in adopting this approach.

What Is Docs as Code?

Docs as Code is a deceptively simple paradigm – documentation should always be written using the same tools as the code itself, and this approach should result in workflows and organizational structures that allow this to happen. While this sounds quite simple, the actual implications of the paradigm can be far-reaching. Let’s take a look at each element of the concept.

Using the Same Tools for Code and Documentation

Firstly, the idea that documentation should be written using the same tools as the code itself comes from a desire to marry the documentation with the system from which it derives. Too often, documentation is difficult to find, and once found, it is hard to compare on a one-to-one basis with the code itself. When developers have to exit a system to understand the system, things get overly complex quite fast. Just imagine using a help menu for your operating system that requires you to open a completely separate computer using a different operating environment.

Developer documentation also tends to be out of sync with the code base at some point — inherently, separation between code and the documentation makes it much harder to keep in sync. It also is likely that the team responsible for the efforts around documentation is at least partially separate from the team creating the code. As such, it becomes ever more likely that as that separation grows and the codebase becomes more complex, more errors in the documentation are possible, if not probable.

Thus, Docs as Code suggests that you eliminate this step of complexity by simply using the same systems for both!

Mirroring This Approach with Workflows and Organization

By adopting a merged approach that uses the same tooling for code and documentation, it becomes much easier to streamline the entirety of the system and, by extension, the underlying structures. The next part of the Docs as Code approach takes this into consideration, and suggests that both the workflows and the organizational layout should reflect this merger.

What does this mean in practice? Simply put, documentation writers should be integrated into the development teams, and documentation should become a critical and regular part of the development cycle. As systems are developed, they should additionally result in documentation that is closely aligned with the resources developing the systems in question — in other words, developers should be involved with or even be the authors of the first draft of each piece of documentation, accurately reflecting the development as it occurs before release. The same processes which apply to code (code reviews, automated testing, issue tracking, etc.) should also be used on the documentation, with the documentation almost becoming an aspect of the code rather than an external reference guide.

Taking this one step further, we can see organizational changes that come with such a workflow shift. Instead of having a documentation team external to the development team, these developers become documentation leaders themselves, either appointing developers to the task of documentation or ensuring that such documentarians are equipped with the same skills, knowledge, and systems as the regular development team.

What Does Docs as Code Do?

So what exactly are the benefits of Docs as Code?

First, and perhaps most importantly, Docs as Code erases the artificial barrier between developers and those who create content around those developments. In traditional workflows, the documentation is often handled separately from the development of a system. While this is acceptable to some degree, it often results in the aforementioned drift between development and the documentation required to understand the development. Adopting Docs as Code closes this gap, resulting in a culture of highly interconnected development and a greater understanding at the team, corporate, and user level.

Additionally, Docs as Code standardizes how documentation is prepared and consumed. The way documentation is provided is just as important as what is being documented, and the reality is that the relatively limited number of mainstream development environments (limited in comparison to the almost infinite number of text editors, at any rate) create a generalized standard form factor by which documentation can be created and consumed. This conformity to a widely adopted and effective standard can dramatically improve the end-user experience. It can help create a firmer pathway to discoverability than simply packaging documentation in whatever format a documentation team chooses.

Adopting Docs as Code allows an inversion of the traditional development-blocks-documentation paradigm. Generally speaking, documentation has always been hindered by development in a workflow sense — you can’t document something that hasn’t been developed, and thus documentation has almost always occurred after release. While this is fine in many use cases, it results in a situation where something must be released and then documented. In adopting Docs as Code, this relationship can be inverted and be built as an automated function in the workflow itself. As things near release state, that release can be blocked by the absence of documentation. While not every team can (or should) adopt this approach, the fact that it is enabled is unique to the Docs as Code approach.

Notably, Docs as Code also provides a robust version-tracking approach. Any sound code development system will have version tracking and author attribution, and if developers choose to use these systems for code documentation, those benefits are delivered to the documentation. Users can see exactly how up-to-date the documentation is, who wrote it, and who they might need to contact to get something corrected, fixed, or clarified. This ability is typically missing in most documentation systems.

That is really the biggest benefit of this system. Code development brings with it specific tools and systems that have proven their value time and time again. Issue tracking, version control, and automated testing — these systems provide a way to verify that the documentation is accurate, complete, and useful. As such, they have obvious value in implementation in the documentation.

The idea that the documentation should exist separately from the code instead of integrated in the code approach seems strange now that we’ve seen the benefits that can be drawn from the Docs as Code approach, but the reality is that documentation has often been an afterthought at best — adopting Docs as Code elevates documentation from an afterthought to a critical component!

Drawbacks of Docs as Code

Docs as Code is not a perfect solution for every team for various reasons. Firstly, Docs as Code requires significant technical knowledge for anyone writing the documentation. For simple systems, the person writing the documentation doesn’t always need to be the most technically savvy, especially if the people using that documentation are more likely to be customer service team members rather than developers. In such a case, adopting Docs as Code can create a high threshold that carries with it many blockers in implementation.

Additionally, the documentation from Docs as Code assumes that your code is inextricably linked to the documentation. While this is true in many situations, there are many cases in which the documentation should be changed more frequently, reviewed in a different pattern, and perhaps written for a different audience.

In such cases, simply adopting the Docs as Code pattern can lead to mismatched systems. Sometimes, you just need a simple typo fixed or a piece of documentation for sales purposes. Tying these documentation systems to the code could create added complexity and result in workflow and organizational output issues.

Standard Tools and Specifications

With this knowledge, where does one even start? Luckily, there are some great tools out there that can help development teams adopt a Docs as Code approach.

The obvious choice here would be systems like Git, which provide a robust version control system and a great text editor and presentation layer. Git is also built into many coding environments, making it a clear choice for teams who want to engage in documentation with relatively low overhead and an extremely shallow learning curve.

Markup languages also provide a wide range of benefits and are likely already being used extensively in your codebase. For example, Markdown is commonly used to structure and format codebases. As such, it can be used to deliver excellent documentation while mirroring the way the codebase is already presented.

Automated solutions for endpoint testing or hosting automation like Netlify can also allow you to automatically generate new documentation based upon specific actions, such as pull requests, updates, or endpoint changes. These tools can make documentation iteration automatic and easy, assuming the documentation is built from the get-go and routinely tested and verified.

Conclusion

Docs as Code is a great solution for many teams, but it does come with its drawbacks and considerations. If you meet the circumstances that make Docs as Code a good option, adopting it can result in huge dividends in team health and end-user experience.

What do you think of Docs as Code? Are there other paradigms you’d like to see covered on Nordic APIs? Let us know below!