<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=1919858758278392&amp;ev=PageView&amp;noscript=1">

Riona MacNamara

Riona MacNamara


Session Name: The Knowledge: Towards a culture of engineering documentation

Documentation is core engineering work. In theory! In practice, nobody seems happy with the docs. For several years, Google's internal surveys identified the lack of trustworthy, discoverable documentation as the #1 problem impacting internal developer productivity. We're not alone: Stack Overflow's 2016 survey ranked "Poor documentation" as the #2 problem facing engineers. Bad documentation is bad: Bad for velocity, bad for quality bad for reliablility. And it's especially problematic for SRE, who "live and die by the docs." Solving this problem is tough. It's not enough to build tooling; the culture needs to change. Google internal engineering is attacking the challenge three ways: Building a documentation platform; integrating that platform into the engineering toolchain; and building a culture where documentation - like testing - is accepted as a natural, required part of the development process. In this talk, we'll share our learnings and best practices around both tooling and culture, the evolution of documentation, and some thoughts about how individuals and teams can use reporting and communication to drive change in their organizations, and convince management and leadership that documentation is core engineering work that is worthy of funding, recognition, and reward.

Speaker Bio:

Ríona is senior staff technical writer at Google, where she manages the Google Cloud documentation team focused on developer tools and languages, CI/CD, Serverless, and Observability. In her 13 years at Google, she also drove efforts around open source documentation strategy, and previously led the team that built g3doc, Google's internal platform for engineering documentation, used by thousands of projects within the company. Before Google, she worked at Amazon and spent almost 10 years as a writer, editor, and program manager at Microsoft. She is a frequent speaker on documentation, diversity, and inclusion. She will not rest until documentation is fully integrated into engineering culture and workflow.