What is Docs Like Code?

It’s variously known as ‘docs like code’, ‘documentation as code’ and ‘docs as code’. The basic ideas stay the same, though: treating documentation just like you’d treat your programming code.

Why do people use docs like code?

As we modify a piece of software, we should also be modifying its manuals, online help, and tutorials. Historically speaking, we’ve often treated the two fields quite differently, with different development cycles, approval structures, and build processes. But that different treatment often leads to trouble. We end up with large, unwieldy documentation suites that are out of date, badly organised, and not edited to a decent standard.

How docs like code can help

When we use docs like code, we treat documentation like source code. That means we:

  • adhere to the same methodology (for example, agile sprints)
  • use the same workflows
  • have the result tested by the same testing team
  • add it to the same Git or CVS repository
  • use the same build tags.

We can modify documentation as we modify the code base, and our testing protocol can compare new documentation to new functionality.

Docs like code brings documentation into the same developmental cycle.

What you’ll need

Moving to a docs like code mindset requires learning some new skills. If you’ve come to documentation via software engineering, most of these will be familiar to you. 

Single-sourcing

Also known as ‘write it once’; create documentation in small chunks that can be slotted into a build wherever needed, but only exists in one location in the source material. For example, I might have some information about system requirements for a piece of software. I need to publish it in the Installation Guide, the Getting Started Guide, and the Knowledge Base. If I write all three documents as big singular files, I’ll have to update that information in three different locations whenever it changes. The other option is to write it once in a small piece of text, and link it into three different documents. When those documents go through the build process, it’s included in all three… but I only ever change the small source document.

Decrease maintenance by re-using a single snippet of information in multiple places.

Markup languages

We can use markup languages to create a single set of source documents in a ‘code-like’ environment. Then, we combine a number of those documents and build them into HTML, LaTeX, PDF, or other document formats. We can publish all sorts of documents from the one pool of markup documents. Common markup languages include Markdown, ReStructuredText (RST), and LaTeX.

Build multiple documentation formats from a single base.

Version control

One of the biggest headaches I’ve ever experienced was caused by a documentation suite that spanned five different software versions, and updates had been constantly added to the incorrect version of the manuals… meaning that I had to map software features to documentation for every version, and correct as I went. This is a terrible but fairly common situation for a company to get into when version control hasn’t been considered for documentation.

When we combine single-sourcing and markup languages, though, it becomes simpler to tag each source document with the software version it supports, and to publish documents built from only the correct source material. I’ve mentioned Git and CVS because I’ve used those most, but we can include doc like code in pretty much any version control software used for code.

Use version control to keep your end documentation specific to a product release.

Variables

When we use variables in documentation, we can dramatically cut down on maintenance requirements. We assign a variable to anything that is likely to change regularly, and we can even dynamically change the value used by modifying build parameters. When two products have overlapping functionality and hence documentation, we just use the same source documents with a variable for the product name.

Use variables to decrease creation and maintenance times.

Issue tracking

When we talk about treating documentation like code, that goes all the way through to testing and bug reporting. Adding documentation to your issue tracking solution ensures that any problems are dealt with quickly.

Let your users log documentation issues.


Would you like to chat about converting your documentation suite to docs like code? Request a documentation consultation.

 

One Response

  1. […] tags to specify basic formatting options, which can be built upon later. It can be used to create docs like code, so is often popular in software development environments. It has a lot of similarities to […]

Leave a Reply

Your email address will not be published. Required fields are marked *