How to get the most out of software documentation

Jan 11, 2022 · 6 min read
Sharon Gaudin GitLab profile

It’s not a glamorous part of a DevOps platform, but software documentation is easy, sometimes hands-free, and, if done correctly, can help speed up development and deployment. Here are some tips to refresh your software documentation practice.

Defining documentation

Software documentation – which includes everything from manuals to system and design requirements, change lists, code comments, and alert records – is a way to unify efforts between projects and DevOps teams, and to share specialized knowledge and guidance. It’s also a way to standardize practices and benchmark metrics. There’s a direct correlation between creating clear, comprehensive, searchable, up-to-date, and well-organized documents and a DevOps team’s success.

Need proof? According to the Accelerate State of DevOps 2021 report from DORA, the DevOps Research and Assessment team at Google, DevOps teams with solid documentation practices are 2.4 times more likely to meet or exceed their reliability targets, 3.8 times more likely to implement security practices, and 2.5 times more likely to fully leverage the cloud.

Making sure you have strong documentation actually is one of the six suggestions the DORA report gave DevOps professionals who want to become elite team performers.

As you work on a DevOps platform and create new efficiencies and processes, you will want to document them so you can carry them forward. No continually reinventing the wheel for you.

Tips for creating solid software documentation

So how do you go about building good documentation? Here are some basic steps to follow:

Continuous software documentation

Much like there are continuous integration and deployment, there also can be continuous documentation. You can make the automated processes on a DevOps platform do a good chunk of your documentation work by having them capture key information throughout the DevOps lifecycle and funnel it into your documentation stores. Make it part of your development workflow by approaching documentation with a DevOps mindset. Software documentation is easier and more helpful when it’s done continuously.

You can leverage existing tools to generate, convert and present documentation. GitLab provides an extensive REST API, which allows to update the wiki programmantically, or modify a Markdown file in the Git repository from your CI/CD pipelines. If you want to present the documentation on a website, you can use MkDocs to generate a static documentation website served with GitLab Pages for example. Code documentation with Doxygen can be generated in the same way as a website reference documentation.

Tips to make documentation easier and more continuous

These are just a few ways to automatically feed your continuous documentation operation. Sure, there are forms of documentation that will need some hands-on, but there are a lot that can be generated as part of the ongoing process. The data is there, so make good use of it.

“Good documentation is foundational for successfully implementing DevOps capabilities,” the DORA report noted. “Teams with high quality documentation are better able to implement technical practices and perform better as a whole… From security to testing, documentation is a key way to share specialized knowledge and guidance both between these specialized sub-teams and with the wider team.” 

Michael Friedrich, Senior Developer Evangelist, contributed to this blog post.

“Better software documentation will help you get more mileage out your DevOps platform. These 16 tips show you how.” – Sharon Gaudin

Click to tweet

Open in Web IDE View source