Docs as Code: An introduction for beginners

This short article will introduce the practice of docs like code: what it is, its pros and cons, some of the skills and tooling involved, and how to decide if it’s right for you.

What is docs like code?

Docs like code, also called docs as code, is the practice of treating documentation development in the same way as code development. Documentation can be anything from webhelps, to auto-generated API docs, to context sensitive help.

A docs like code approach has two key implications:

• Use the same tooling as your development and devops teams: this includes version control and automated deployments.
• Use the same techniques as the developers: this may be a version of Agile, or whatever development practice your company embraces.

This doesn’t mean you have to do things in exactly the same way as the development team, but you should generally aim to be close. For example, you might want to choose a static site generator designed for producing docs, but still keep docs under version control, add the docs build and release process to the same deployment pipelines as the code, and so on.

Pros and cons

As with any tech paradigm, docs like code has its pros and cons. Some of these are situational - docs like code is more useful for some companies than others, for instance.

Pros: 

• It allows you to reuse both software and human resources: a software company almost certainly already has expertise and tools for version control, automation, modern build processes and so on. By using the same tools and processes, you reduce costs and increase the number of people at the company who can support the docs. This in turn helps avoid documentation becoming a silo.
• It helps you work closely with development: by sharing processes, and using tooling that devs are comfortable with, you open up the docs to easier collaboration. For example, if you need developers to review your docs, they’re likely to already be comfortable doing this on GitHub as part of a pull request.
• The power of automation: docs like code tooling tends to be customizable, and support modern web technologies. This makes it possible to embed autogenerated docs, set up automated tests to check for everything from style adherence to whether screenshots are up to date, automatically deploy demos, and more.
• It allows you to write in a lightweight markup language. If you’re a writer who finds this quicker than using a WYSIWYG, this is a big improvement to your writing experience.

Cons: 

• It requires technical knowledge and increases the tech skills threshold for technical writers: creating and managing a docs like code webhelp usually requires familiarity with modern web development tools (especially static site generators), and with other common dev tooling such as git. Some tech writers may love diving into the command line and wrangling tooling. Others may be put off. This has implications for hiring and training.
• It works best for documenting software: if the documentation is writing directly about the code, it makes sense for the docs and code to be close to each other (this is where you can take advantage of autogeneration). If your company is a software company, you still benefit from reusing resources. The advantages of docs like code decrease for other types of companies.
• If you prefer a WYSIWYG writing experience, be aware that most static site generators don’t include a WYSIWYG editor. You can add one using one of the (many) CMS products for static site generators, but this is additional setup effort.

Skills and tooling

There’s a bewildering variety of tools available for docs like code. For all of them, some degree of training (whether official or self-taught) is required. In general, a standard docs like code pipeline would include:

1. Documentation written in a lightweight markup language, such as Markdown or AsciiDoc.
2. Version control (often, but not always, git), probably combined with a remote version control host such as GitHub or GitLab.
3. A static site generator to build the docs. Static site generators are tools that take content and template files, and generate websites. There are hundreds of static site generators, some purpose-built for documentation.
4. Automated documentation deployments. This might use tooling such as Atlassian Bamboo, or Jenkins, but can also be handled more simply: some hosting providers, such as Netlify, support automated builds triggered by version control actions (such as a pull request on GitHub).

Before diving in, researching dozens of tools and creating your own solution, talk to the developers and devops people at your company. What are they already using? It’s likely a lot of the choices have been made for you.

A quick note on static site generators

The biggest decision you’re likely to make is which static site generator to use. This can affect what documentation features are available to you, what markup language you write in, and how you customize the look and feel of your docs.

As with any docs tool, think about who is writing the docs, and who is maintaining them. This may affect what markup language you prefer, for example.

I won’t go into a detailed static site generator comparison here, but a few tips when narrowing down your selection:

• What can your developers support? If you need developer help with design and setup, it may make sense to use a tool based on the same programming languages the devs use. For example, if all your software is built with Vue.js, it’s probably worth evaluating Vue-based static site generators.
• Is the SSG actively maintained? Ideally, it should also have a good community around it, so you can ask for help if needed.
• Does it support basic documentation features, such as content reuse, easy-to-manage table of contents and navigation, search, conditional outputs and so on? You may find it better to go with a tool designed for documentation, even if that means using something built in a language your devs aren’t as familiar with.

Is docs like code right for you?

By now, you may be getting a feel for whether docs like code is right for you. Here are a few questions to ask yourself and your docs team before adopting it:

• Do you have the technical skills you need, or can you get the time and resources needed to learn them?
• Will other people at the company be willing to support this approach?
• Does it bring you benefits? For example, will it be an advantage to have easier collaboration with development? Can you make good use of automation?
• What outputs do you need? Docs like code is best at producing online help. You certainly can produce PDFs or other formats, but it may be more difficult. If you need to single-source content into several different formats, consider how long it would take to set this up with docs like code tooling.
• Are you excited about both the approach and the tooling? Like any development paradigm or software tool, it’s far easier to work with it when you enjoy it.

Conclusion

This article has given a very high-level introduction to docs like code, along with some suggestions for tooling choices and how to evaluate if it will work for you. You can read more about the paradigm at the Docs Like Code, and it’s worth checking out their book for a deeper dive into the topic.

If you’d like to try out some new knowledge base software, sign up for a free trial of KnowledgeOwl right now.