Writing Sample: Docs as code - Why bother, and how to start writing documents as code

This page is an introduction to Documentation as Code (docs as code) - an alternative approach to creating and maintaining documentation in software development teams.

You should read this if you are a technical writer and want to work better with development teams. By the time you finish reading this, you should be able to:

• explain the process that a docs as code approach entails.

• have a plan to transform the documentation process in your organization.

This article assumes working knowledge of Agile software development and technical documentation processes. If you feel like you could do with a refresher then the links above are a good place to start.

What is docs as code

Docs as code refers to a philosophy that you should be writing documentation with the same tools as code, and within the same process as software development.

These tools include, but are not limited to:

1. Issue tracker tools such as Jira 2. Version control tools such as Git 3. Plain Text Markup languages such as Markdown 4. Where possible, a docs as code approach also entails automating review processes and other software development best practices such as Continuous Integration and Continuous Deployment.

Why use docs as code

The most common way that documentation is created in most organizations is by using a what you see is what you get (WYSIWYG) Content Management System (CMS). Once documentation teams have gathered information from developers, they write it up and post this information to a website using a CMS like WordPress, Squarespace, Madcap flare and so on.

Let’s look at how a docs as code approach improves upon the standard approach:

The Standard Approach	Docs as Code
Development and documentation teams are completely siloed.	Documentation teams work in the same process and use the same tools as development teams.
Documentation often comes after development which means you can’t release your docs as you release your product.	Documentation is written alongside new feature development, not after.
The actual writing of documentation is almost never owned by development teams.	Developers take ownership of documentation when they can treat docs the same way as they do code.

Research on best practices for documenting code has shown that docs should be written when code development is still fresh in the developer’s mind. When developers are asked to recall details that are no longer at the forefront of their minds, the quality of information that you get, and consequently your customer facing docs are likely to suffer.

How does it look in practice?

To keep it simple, let’s assume your company follows the typical Agile software development process. Here is what a docs as code approach would look like in parallel with Agile software development.

Agile software development	Docs as Code
Define new features	Define documentation deliverable
Write code	Write docs in Markdown and maintain content in Git
Build an executable	Push content to a website
Test code	Review and run validation checks
Release new features	Publish docs

Tools and practical recommendations

Much like you need a translator to speak to someone in another language, you need a website generator for docs as code. A website generator interprets Markdown (docs written as code) to a readable format (a website) for your end users.

There are many website generators available, but one of my favorites is Gitbook. Gitbook brings the best of both worlds together – enabling developers to push first drafts of content from tools that they love, and enabling product teams or technical writers to review and publish from a state of the art wysiwyg environment. You can connect your account to git and publish directly from there as well.

So what's next?

Whether or not you are ready to adopt a docs as code approach in your team will depend on the appetite for change in your organization, ability to self-train and many other factors. I recently started implementing this approach for one of our teams. We have started building in the process and are slowly getting rolling out the tooling, including Gitbook. If you want to try it out for yourself, I recommend you start by:

1. Editing a simple Markdown doc.

2. Signing up for a free account on Gitbook and following their guide on how to get started on your docs as code journey.

There are so many success stories out there, so why not start yours? Good luck, and happy writing!