Internal documentation is a fundamental part of software development. Analysis by DORA has found a clear link between documentation quality and organizational performance — the organization’s ability to meet their performance and profitability goals. Documentation is highly technical work, and our findings show just how much this work pays off.
Measuring documentation quality
For our research, we used a set of eight metrics that assess documentation attributes like clarity, findability, and reliability. You can review the questions from 2022 for the statements we used to assess these attributes.
The impact of documentation
Similar to our research from 2021, we see documentation quality driving the implementation of every single technical practice we studied. Our model from 2022 shows documentation underpinning these technical capabilities.
What may be more exciting, however, is how documentation quality interacts with these capabilities to impact organizational performance.
This interaction and impact applies to every single technical capability we studied in 2022. In the table below, check out the lift to organizational performance as various technical capabilities are implemented. The lift is significantly amplified for teams with above-average documentation quality.
Creating quality documentation
Documentation needs to be actively created and maintained, which takes work.
For guidance from our research, you can review the 2021 State of DevOps Report for practices that you can implement to improve documentation quality.
This research doesn’t investigate individual resources, but there are plenty out there to help you create useful documentation. In your own organization, you may have documentation guidelines and training. You may also have technical writers or other documentation champions to work with. Here at Google, our documentation resources include:
-
Technical Writing Courses for software engineers
-
The documentation chapter of Software Engineering at Google
If you’re lucky enough to work in an environment with plenty of quality documentation, it’s because you or people in your organization create that content. But if your organization has poor quality documentation, there’s good news. By implementing the practices linked above, you can improve your documentation quality and make it shine.
Excerpted from 2022 State of DevOps Report data deep dive: Documentation is like sunshine by Michelle Irvine and Derek DeBellis