97 Things Every SRE Should Know

Chapter 16. Use Your Words

Tanya Reilly

Squarespace

When it comes to reliability, we’re used to discussing new advances in the field, but one of the most powerful forces for reliability is also one of the oldest: the ancient art of writing things down. A culture of documenting our ideas helps us design, build, and maintain reliable systems. It lets us uncover misunderstandings before they lead to mistakes, and it can take critical minutes off outage resolution.

Code is a precise form of communication. A pull-request reviewer can mentally step through a change and evaluate exactly what it does. What they can’t say, though, is whether it should do that thing. That’s why thorough PR descriptions are so important. To evaluate whether a change is really safe, a reviewer needs to understand what the code author is trying to achieve. Our words need to be precise too.

Words give us a shared reality. They force us to be honest with ourselves. A system design that felt quite reasonable during whiteboard discussions might have glaring holes once the author is confronted with describing an actual migration or deployment plan or admitting their security strategy is “hope nobody notices us.” An RFC or design document spells out our assumptions. They let us read each other’s minds.

A culture of writing things down reduces ambiguity and helps us make better decisions. For example, an availability ...