‘Documentation as code’ matters. Here’s why

There has long been a mindset to treat documentation and code as separate functions. But this thinking is obsolete. Organizations should start treating documentation as code.

Development projects are not complete without documentation that is in the same state or better as the code. That said, often documentation is considered a major pain point involving high effort with no automated way to control quality.

While writing documents may be labor-intensive, in the absence of integrated tools, maintaining the docs is even more tedious. And it can be cumbersome to create cross-references to other articles, sections and APIs, and to keep track of broken links — all while writing new content.

Furthermore, traditional methods of documentation focus on the concept of a printed page. Most documentation in today’s age is never printed. Most users consume content through their laptop, tablet or mobile phone. The resulting formats are quite different in size from the printed page. The documentation created with traditional page-oriented methods does not adapt well to these different devices.

The tools, environment and proprietary file formats can make documentation harder to maintain and update. Teams struggle with multiple versions in circulation. They may update the wrong version, and issues like rebranding across multiple documents can become difficult.

Fortunately, there is a better way: “documentation as code” addresses the need for multiple formats and ease of maintenance.

Make documentation part of the build

Doc-as-code allows us to make documentation part of the build process — using the same tools. This approach to documentation empowers developers and writers to apply the same methods and rigor used for code to the associated documentation. The tools and environment address aspects like version control and change management, thus making it easier to keep documents and code in sync.

With doc-as-code, content can be sized automatically to fit the consumer’s device. Doc-as-code provides new capabilities to leverage content, does a better job of version control, and automates related work like spell-checking.

Easy to consume, search and maintain

The doc-as-code document content is in a plain text file. Simple markdown or HTML tags can be added for advanced formatting. Tools like ASCIIDOCTOR can automatically extract these tags, notes and comments and publish the documents on platforms such as Git, GitHub, Wiki and content management tools. There are several tools, including Jekyll, Hugo and MkDocs, that can create good quality documentation from markdown. Continuous documentation as part of the continuous integration pipeline simplifies the effort to keep docs updated with every code change.

Doc-as-code offers multiple benefits:

  • Online content makes document information easy to consume.
  • Documentation is no longer designed for the printed page, and the information can be consumed on any device.
  • Content exists in one place but can be pulled into other documents as needed (imagine changing a copyright date once and that change propagates to all your documents).
  • Content keeps current with code changes.
  • Content is searchable within and across documents.

Continuous integration, continuous delivery, continuous documentation

With agile and DevOps adoption on the rise, and the focus on continuous integration and continuous delivery at the center of development engagements, treating documentation as code is gaining traction each day. The need for marrying the culture of coding with the practice of writing is evident as both developers and writers understand the value of integrating documentation into the development process. Doc-as-code is an idea whose time has come.

In the next post, we look at how to get started with doc-as-code and the tools that can give you a head start.


AnnuAnnu Singh is a digital transformation advisor at DXC Technology and is part of the Digital Transformation Center (DTC) team. She collaborates with the DTCs and DXC Labs to promote emerging technologies and is a proponent of documentation as code at DXC. Annu is also an active chair of DXC’s Women in Leadership India Chapter. @Annu_Singh_Tom

Comments

  1. Simple and Elegant Introduction to the Topic

    Liked by 1 person

  2. Nishchal Srivastava says:

    Very nice article! There could not be a better way of presenting documentation than the one which is integrated and completely aligned with code using a dynamic format. The concept of documentation-as-code is sure to have a 100% usability.This is bound to increase maintainability of documentation as well as code because both depend upon each other.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: