Docs Or It Didn't Happen: Integrating documentation into DevOps culture

Trustworthy, comprehensive documentation is as core to the discipline of DevOps as testing. In an ever-more complex ecosystem, documentation is critical for development velocity, code quality, continuous delivery, and the reliability of services in production - yet developers consistently report its lack as the most significant productivity problem they face.

The challenge is that while every developer needs documentation to do their job, most developers dislike and avoid creating it - and as long as doc work is perceived as low-status drudgery that takes time away from coding and goes unrecognized and unrewarded, neglecting it is entirely rational behavior.

In a world defined by complex, ever-shifting ecosystems, this situation just isn’t sustainable - but fixing it requires us to foster a culture that recognizes documentation as core engineering work that is worthy of funding, recognition, and reward. At Google, we believe that doing so requires changes to both tooling and culture.

In this talk, Riona will describe how Google created tools that integrate documentation into the engineering workflow, making documentation not only easier to find, create, and maintain, but also enabling us to integrate it with our tooling and knowledge systems and creating a culture where docs are increasingly a normal, natural, and expected part of the engineering role. Riona will also share practical tips and best practices gathering data around documentation quality and effectiveness, and using that data to convince your team, your organization, and your leadership that investing in documentation is worth doing as part of your DevOps process.

Because it is.

Speaker

riona-macnamara

Ríona MacNamara‎

  
Ríona is senior staff technical writer at Google, where she manages the Google Cloud Platform documentation team focused on CI/CD. In her 12 years at Google, she also drove efforts around open source ...