This week, we dig into the DORA report to review a frequent topic on engineering teams: documentation. We’ll put data behind some well-known benefits of better documentation, as well as some important costs that teams should be mindful of and avoid.
Note: this article contains a sample of the report that we found most useful to our readers. To dive deeper into the data, take a look at the full report.
The context:
The DevOps Research and Assessment (DORA) team focuses on understanding the relationship between capabilities and outcomes. For almost a decade, the DORA team has assembled and analyzed data from over 36,000 professionals. The annual DORA report is a rich analysis of what factors contribute to high-performing engineering teams, and what actions teams can achieve great outcomes.
Good documentation is foundational, and has a positive impact on team performance, productivity, and job satisfaction. Researchers looked at how impactful documentation is on various aspects of software engineering, and found that broadly speaking most aspects of software engineering are significantly improved. However, they also noticed that documentation can negatively impact the well-being of certain teammates. So what are the benefits, and costs, of documentation? And how do we mitigate those costs?
The research:
In their extensive research survey, researchers analyzed how improved documentation impacted various technical capabilities. The results were clear: compared to teams with low documentation quality, teams with higher documentation quality saw a lift in every technical capability they measured.
Next, researchers looked at how documentation impacts well-being and team outcomes. The results are shown below:
In analyzing the results, researchers found that:
- Better documentation substantially decreases overall burnout, and increases job satisfaction and productivity
- Better documentation also substantially improves team performance, organizational performance, and operational performance. Interestingly, software delivery performance (i.e the standard DORA metrics) showed no effect - this was the second year the researchers observed this trend
Researchers also discovered an unexpected trend - for respondents who identified as underrepresented, documentation was tied to an increase in burnout.
The researchers decided to dig into these findings more and found that:
- Gender had no impact on these results. Respondents across all genders saw a decrease in burnout with increased documentation, but respondents who identified as underrepresented (regardless of gender) had a higher rate of burnout.
- The finding was similar for documentation quality, generative culture, and team stability: as these attributes increase, burnout also increases for underrepresented folks.
Why this trend? Researchers theorized that it’s likely that documentation efforts might not be recognized for its importance and impact. It takes a lot of effort and technical knowledge to maintain high-quality documentation, and the data may point to the fact that underrepresented groups are doing a disproportionate amount of this work. More research is needed.
The application:
Having good documentation has countless benefits for engineering teams. From operational performance to job satisfaction, teams improve their overall productivity and quality through documentation. However, making an investment in documentation can come at a cost for some teammates if not well-managed. Here are some tips for managers thinking about improving documentation:
- It’s an investment that helps you move faster. Often, particularly for fast-moving teams, documentation may feel like it slows the team down. But the data overwhelmingly shows that the investment in documentation improves all aspects of team performance, and is worth the incremental investment.
- Recognize documentation for its impact. When teammates know that documentation has an impact on their performance, they will prioritize it against their other feature work. One way of doing this is to include knowledge sharing as a part of the team’s performance conversations. This will build a team culture that views both documentation and broader knowledge-sharing as important for overall performance.
- Be careful of who gets “glue work”. Glue work (as thoughtfully detailed in this post) refers to the non-promotable work - like documentation - that needs to be done for a team to succeed. It is critical work, and yet it often falls on underrepresented groups - for example, women are 48% more likely to do non-promotable work. Be careful of who on your team is more often doing glue work by auditing the distribution of these tasks over the last 3-6 months. You can mitigate against it by assigning and rotating teammates to do this work and helping them understand why it matters.
—
To receive weekly editions of research-driven insights, subscribe to our newsletter, Research-Driven Engineering Leadership.
