How to automate your documentation using GitHub actions

Introduction

If you’re a SaaS company, developer documentation is an essential part of your content strategy. 90% of technical stakeholders admitted that their purchasing decisions were influenced by the quality of the product’s documentation. That is a staggering number of clients who are willing to open up their wallets based on how approachable your “Getting Started Guide” is.

Unfortunately, documentation is in a sorry state of affairs for tech companies large and small.

Earlier this year, I conducted user interviews with several tech companies. They varied in size and stage, but all of them were selling a product marketed towards developers. And all of the companies were struggling with producing and maintaining quality documentation. Some of the problems they faced included:

• “No one owns our docs.”
• “Our docs are constantly out-of-date.”
• “Our engineers wrote the docs, and it doesn’t sound professional.”

These problems are not unique, but they are blocking companies from realizing their full revenue potential. Fortunately, there is a solution to bad documentation. Automation.

When we say “automation,” we’re referring to tools such as Git, Github Actions, and documentation generators like PyDocs and Sphinx. These tools are the “robots” that will save the day!

Problem # 1 No One Owns the Documentation- Lack of Accountability

Sometimes knowing who is in charge of writing the docs is a complete mystery. There is no record of who made which change, or it’s not worth the effort to hunt down the person who incorrectly wrote the purpose of a new feature. The docs as code workflow fixes this.

What is Docs as Code Workflow?

The docs-as-code workflow is where your documentation is written in markdown and version-controlled with git. Many developers use git as a way to manage their code and collaborate. Documentarians can do this too! The advantage of docs as code is that you can figure out:

• Who has written the documentation with “ git blame. ” You know exactly who has written which part of the documentation with git blame. Complete transparency.
• If you’re using git and GitHub, you can implement a Pull Request. A pull request is a Github feature where a writer can add changes to the documentation and request review and approval from another writer before those changes are added to the docs.

Using Github and the docs-as-code method is an excellent way for writers to create a culture of ownership and accountability.

Problem #2 The Documentation is Out-of-Date

Deploying is no longer a rare event that happens once a quarter. Engineering teams are constantly adding new features to their product, so it’s not unheard of for programmers to release changes several times a day. The problem with this is that the documentation quickly becomes out of date.

Pydoc and Sphinx

Not all documentation needs to be written by tech writers. Some documentation can be generated by the code. Tools such as Pydoc generate documentation from Python modules. Sphinx creates documentation from docstrings and creates HTML and LaTeX output.

This is useful because it empowers developers to keep their API documentation up-to-date without involving the writers. Even though it is best practice to include Getting Started Guides and high-level tutorials, an up-to-date API reference is a fair starting point!

Git to the Rescue…Again

You can’t address old documentation if you don’t even know that your docs are out of date.

Some teams still store their docs in a tool like Microsoft Word or Excel. Even though Word and Excel are convenient tools, they are not good at timestamping content creation. This is where git shines. If you’re using git in conjunction with GitHub, you can tell the last time the documentation was updated.

The bottom line is there is little excuse for your documentation to be out of date. There are plenty of automation tools out there like Pydocs and git to help you ensure that your documentation is an accurate representation of your product’s features and codebase.

Problem #3 The Docs Don’t Sound Professional

This common problem occurs when the engineers are 100% in charge of writing the documentation. This doesn’t mean that the engineers are bad writers. Usually, it’s that they don’t have a process in place to help them.

If you’re looking for documentation that is consistent in tone and voice, the first thing to do is to implement a style guide. A style guide is a list of technical documentation best practices and rules. If you’re curious about learning more about style guides and writing for end-users, take a look at Strategic Writing for UX and The Art and Business of Online Writing.

You don’t have to create one from scratch, you can “borrow” one from Microsoft or Google.

How to Automate Your Style Guide

Now it’s time to bring in the robots! 🦾🦾🦾🥳🥳

It can be quite tedious to constantly refer to a style guide when writing the details of a new feature. The best way to make sure that a style guide is being used is to automate it!

When you are programming in Python or JavaScript, you usually use a tool called a linter. A linter standardizes the indentation and spacing of the code, so the team doesn’t have to fight over aesthetic changes. Tab vs. spaces, anyone?

Writers can also use a linter like a vale, which automatically checks that the documentation is following the agreed-upon style guide. You can run the linter on your local computer or create a continuous integration and delivery pipeline or CI/CD. In this scenario, the writer would push their documentation changes to Github, and a Vale GitHub action runs a check on the writing before the writer can add their changes to the already published documentation.

If you’re interested in setting this workflow up for your own team, I published a How-To guide about automating your style guide with Vale and Github actions.

Conclusion

Great documentation is the key to attracting the attention of prospective customers. Fortunately, with the help of automation, keeping your docs readable and up-to-date, and easy to read is no longer a tedious task.