Seeking SRE

Chapter 19. Do Docs Better: Integrating Documentation into the Engineering Workflow

Ríona MacNamara and Shylaja Nukala, with Stas Miasnikoŭ, Aaron Gillies, Jeremy Sharpe, Google, and Niall Richard Murphy, Microsoft

Across the software industry, confidence in engineering documentation is low. Stack Overflow’s 2016 developer survey ranked documentation as the number two challenge facing developers.

This is a problem. Missing, incomplete, or stale or inaccurate documentation hurts development velocity, software quality, and—critically for SREs—service reliability. And the frustration it creates can be a major cause of job unhappiness for developers.

Documentation takes time and effort, and this is especially challenging for SREs. SREs often spend 35% of their time on operational work, which leaves only 65% for development. Time spent on documentation needs to come out of the development budget, and this is challenging if there’s a perception that creating and maintaining documentation is grunge work that might not be recognized or rewarded during performance review and promotion processes.

How can this be changed? How do you make your organization understand the value of engineering documentation, encourage engineers to create and maintain it, and convince management and leadership that doing so is an activity worthy of recognition, funding, and reward?

At Google, we’re lucky to have a strong technical writing organization, but our writers tend to focus on high-impact, high-visibility ...