Do Docs Better: Practical Tips on Delivering Value to Your Business through Better Documentation

Thursday, June 07, 2018 - 4:45 pm5:10 pm

Riona MacNamara, Google


Missing, incomplete, or stale/inaccurate documentation hurts development velocity, software quality, and—critically—service reliability. And the frustration it causes can be a major cause of job unhappiness.

SREs often spend 35% of their time on operational work, which leaves only 65% for development. Time spent on documentation comes out of the development budget, and this is challenging if there's a perception that creating and maintaining docs is grunge work that may not be recognized or rewarded. To convince fellow engineers and leadership to invest time and resources in documentation, it's essential not only to create good docs, but to gather data that communicates their quality, effectiveness, and value.

Attendees will learn:

  • How to understand and communicate documentation quality
  • Functional requirements for SRE documentation
  • Best practices for creating better, useful documentation
  • How to better communicate the value of documentation work to your business in order to drive change

Riona MacNamara, Google

Riona is senior staff technical writer at Google, where she has worked for 11 years, and leads the team that builds 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.

Open Access Media

USENIX is committed to Open Access to the research presented at our events. Papers and proceedings are freely available to everyone once the event begins. Any video, audio, and/or slides that are posted after the event are also free and open to everyone. Support USENIX and our commitment to Open Access.

@conference {214935,
author = {Riona MacNamara},
title = {Do Docs Better: Practical Tips on Delivering Value to Your Business through Better Documentation},
year = {2018},
publisher = {USENIX Association},
month = jun,

Presentation Video 

Presentation Audio