How to get the most out of software documentation

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:

• You need to decide who is responsible for the documentation. What works best for your team and your organization? Does the project need a technical writer or can one of your developers handle it? Give one person or just a few people ownership of documentation. You’re more likely to have quality software documentation when someone has clear responsibility and no one can pass the buck. 

• Don’t forget about incorporating user experience into your documentation. It will give you a different view on use cases and experiences and enable readers to have their success moment more quickly.

• Think about the security requirements for your software. For instance, when a project uses network communication over public transport, does it provide secure communication with TLS and/or https? Inform users about support policies for security releases, allowing to plan accordingly for upgrades and maintenance windows. Additionally, what measurements do you need to take to make sure it complies with company security policies? Note that information in your documentation.

• Use your documentation to explain technical decisions and share insights into reference architectures. When debugging a problem, it is helpful to learn about the decisions, and also have ‘get help’ and ‘troubleshooting’ sections in your documentation.

• Provide details about issues you faced with the project and how you worked them out. Make sure the details are explained so that others can easily understand them. Add URLs to issues or epics into your documentation to allow readers to follow, for example the version history for product features in the GitLab documentation.

• There should be specific rules about how to change, expand and update documentation. Create documentation style guides, including requirements, examples, use cases and specifications for writing for a global audience. If changes are made creating inconsistent data formats, it can be more difficult to organize and search documents.

• Don’t just document at the end of a project. It should be done continuously throughout the development and deployment lifecycle – from planning through monitoring and feedback. (We’ll give you more tips about this below.)

• Give people who are responsible for documentation the training they need in how to collect data, write, organize, and maintain it.

• Make sure the people responsible for documentation are included in all aspects of the DevOps lifecycle. Bring them into planning, design, and testing meetings. They can’t write about or collect information about what they don’t know is happening.

• Make use of data created by automated processes. (Again, there’s more information on this below.)

• Make sure your documentation isn’t just paraphrasing what the source code flow does. Explain the “why” as well as the use case for the project. Dependending on the size and users, your audiences may differ, and the introduction needs an overview with different navigation routes.

• There’s no one right way to handle documentation. What you need for documentation may vary depending on things like the size and nature of your organization, the scope of your software projects, and compliance issues. A hospital or financial institution’s documentation needs might differ from those of a small, private company.

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

• The DevOps platform’s automated systems, which govern processes and monitor everything from system to software configurations, generate logs that can create a real-time, ongoing stream of documentation.

• Scripts and configuration files that control automated processes, like testing, hold important configuration data that can be fed into documentation.

• Issue and alert logs, which generally contain information about problems, can be automatically documented.

• Integrated Observability keeps track of performance and availability of the software and also can add to documentation by providing access to metrics, traces and log dashboards and panels.

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.