Writing Docs as Code

I recently attended a presentation where the topic was writing docs as code, which prompted me to do a post on the topic. If you’d rather jump right into it, check out the tutorial on this site which will take you through the whole process.

What does docs-as-code mean?

Docs-as-code is an approach to writing technical documentation where the writer uses the same tools and processes as that used by the software developer creating the product. So effectively, you’re giving documentation the same treatment as you would code.

Now if you’re from a non-technical background like me, some more clarification might be in order. The docs we’re referring to are not so much user guides/tutorials or other types of long-form documentation, but rather the type that’s related to APIs, man pages etc.—the sort that developers are likely to be involved in. This documentation in particular, lends itself well to replicating the software development process as the docs can live in the same repository as the code.

A typical workflow when developing software and docs would be write the documentation after the code has been reviewed, tested and merged. With this approach, documentation is an afterthought and an extra task carried out possibly by someone other than the developer.

Writing docs as code, however would mean creating documentation the same way as the software. The whole point is to make it easier for developers to get engaged with documentation—by using a workflow familiar to them, developers are more motivated to write docs.

Docs-as-code Ingredients

Plain text files

The authoring tool can vary from something as basic as Notepad, to the more sophisticated Atom or Sublime Text. There’s also Vim which is an editor used on the command line. The primary format for writing docs in these tools is Markdown, but there’s also reStructuredText and there’s some debate online about which one is better.

Static Site Generator

This is an application that you run on the command line or another UI interface that takes your text files and builds a website from them. Static site generators have become more popular now and are one of the most common authoring and publishing tools used in the docs-as-code approach.

A comparison with CMS:

In a traditional content management system (CMS) like WordPress, whenever a user wants to access content that is stored in that system’s database, a request is sent out to the database which then dynamically populates the site page. So the page needs to be built every time someone wants to view it. This dynamic website architecture played a huge role in moving the web forward, but it wasn’t without its problems (security and cost, to name a couple).

With static site generators, a page is built once locally and stored as a flat file. Any user requesting content with a URL will receive the exact same HTML page. Modern static site generators are quite appealing to developers for many reasons—they are more secure, quickly serve up content, support Markdown which has become more widely used etc.

If you’re curious about the different static site generators out there, there is a very comprehensive list on StaticGen.

Version control system

Source files for documentation are stored inside a version control system like Git or Mercurial. A version control system tracks changes to the files within its repository letting you revert back to an older version at any time. This is the main way developers collaborate and manage their work.

Continuous Integration

The tutorial on this site shows you how to write docs as code using Sphinx and from what I can see, other static site generators like Hugo and Jekyll also follow a very similar process:

• Create content locally in a text file.
• Use a static site generator like Sphinx or Jekyll to generate HTML files and build a website.
• Use a version control system like git to track the changes and push the files to an online repository.
• Publishing happens automatically as a hosting platform is hooked or connected to the repository, and the documentation gets updated within a few minutes of the push.

This is referred to as CI/CD (continuous integration/continuous delivery) and it gets developers very excited. Employing a CI/CD approach means that developers can integrate or implement code changes more frequently, and consequently deliver quality applications to users.

Why use a docs-as-code approach?

Developer doc contribution: It’s a lot easier for developers to contribute to the docs themselves. As a technical writer, you’re meeting them where they are and not forcing them to adapt to your process.

Collaboration: By using the same tools and processes, the approach fosters collaboration between writers, developers and users.

Process improvement: Using large publishing systems doesn’t mesh well with documentation that has to be constantly updated as the product evolves quickly and there are constant releases. Writing docs as code makes for more frequent documentation updates as it mimics the software development process.

Improved doc status: When documentation is subject to the same review and testing process as coding, and errors found are tracked as bugs, we’re giving docs the same treatment as we would coding. The result is a shift in how developers view documentation, and they are more motivated to making it look good.

A side note on man pages

As I was reading up on the types of documentation suited to a docs-as-code approach, I came across man pages—a droll term if you’ve never heard it before. It’s short for manual pages and is the standard for online documentation in Unix-systems. I have a Mac, so I opened up Terminal and typed in man man which gave me back this:

I have no idea what it means, but apparently it’s a man page for a man program. Anyway to create a man page and follow the docs-as-code approach, there’s a formatter called Ronn which converts Markdown to these man pages. I’ll look more into this someday.

Resources:

Tom Johnson’s video presentation

Mason Egger’s video presentation