Documentation as code

As Technical Writers, we all are living the same life. Writing documentation is a fun learning journey, an opportunity to grow, and overall a great career. At the same time, we can’t avoid the perils of writing docs: it’s hard to find good writing tools, it’s is hard to maintain outdated docs, and delivering to the end-users can become a nightmare.

There’s another guild that faces similar challenges, the Software Developers. They need tools to write code, test it, and deploy it. The good news is that they already have those tools.

What if we as writers were able to leverage those very same tools to improve our everyday job and create great documentation? That’s what this post is all about. I will present some of the software tools that will help you to implement docs as code.

Use markup, make your life easier

Most of my life as Technical Writer I have used markup languages, in particular lightweight markup languages (LMLs). I started with rich text editors that allowed for some basic HTML tags. Later on I worked with MediaWiki, reStructuredText, Markdown, and most recently AsciiDoc. The great thing about using one of these is that they are not tied to a particular editor, you can generate different types of outputs (static websites, PDF, epub) from the same source file, and they play along nicely with version control tools.

My favorite markup language so far is reStructuredText (RST), and the perfect tool work with RST is Sphinx. Sphinx allows to build a nice rich documentation website in no time. It is primarily used in Python-related projects, but it’s perfect to document any other software. The official Sphinx website provides a nice Getting Started guide to help you get your feet wet.

There’s another popular approach to technical writing, topic-based writing, which can also be implemented in a docs-as-code workflow. There are a few markup languages for this, I have tried DITA, DocBook, and Mallard. DITA is probably the most popular of the lot.

These tools use XML instead of LML, which in my opinion makes them harder to work with because the format is not very human-readable. Also, topic-based writing may be a challenge; coming up with self-contained chunks of documentations is easier said than done.

Use version control, just do it

The biggest problem that Developers had to solve to truly become efficient in big teams was collaboration. They solved this problem using a version control system.

Version control systems allow to keep track of every change made to the files, including time stamps and who did what. They also offer a reviewing system. There is a learning curve though, and that may frighten some newcomers. All in all it’s worth learning version control, at least the basics.

There are plenty of systems to chose from, but you are very likely to hear about a few: SVN, Mercurial, and Git. Git is by far the most popular. It’s ubiquitous within the industry and a requirement to work as Tech Writer in many companies.

Git is OpenSource and as such every company can set up their own instance, but most of them choose to pay for a service provider instead. Again, there are three popular options here: GitHub, GitLab, and BitBucket. Gihub is the most well-known, but after Microsoft acquired them, they lost many users to GitLab. Bitbucket has more of a niche market, specially appealing for those that already use other products from its parent company, Atlassian.

Keep your documentation on a repository, and if possible keep it in the same place as the code. Your team and specially the Developers are going to love you for that.

Automate publishing, deliver quickly

In recent years, as Agile software development became popular, so did Continuous Development and Continuous Integration. This approach to software development automates the path from the coding team to the delivery of Software. The people in charge of making that happen are known as DevOps.

We can benefit from that very same workflow. Write the docs, test them, push them and see the magic happen. Your documentation shows up online delivered at the same time as the software it enhances.

There are plenty of options for this. Usually the Git providers already offer some way of automation. GitHub does this using TravisCI, GitLab and Bitbucket have their own DevOps tools.

There are also third-party tools, like Jenkins and Bamboo, that will help you get the job done.

This part of the process may be a bit too far-fetched for a Tech Writer. The efficient way in this case is to ask your resident DevOps for help, they will probably set everything up in a jiffy. Once that is done, you won’t have to think about it. Just write the docs!

Further references

For a real-life example on how to implement a CI/CD pipeline for documentation see my post about deploying a Sphinx site with Heroku and Gitlab.

You can find another article about Documentation as Code, with plenty of additional references, at Read the Docs.