Just write it down

Published Nov 25, 2020

I’ve been thinking a lot about the role of on-call engineers lately. Part of that is because I’ve realized that the best way to learn a complex system is to be “in the room” when things go wrong. Another part is that life rolled up a situation where I’m the first person to go twice in my team’s new on-call rotation pattern.

A principle I’ve held for a while is that useful information should be written down and referenced wherever possible. Since you don’t know what information will be useful in the future, and writing it takes real time, there’s an art to deciding what to write and where to write it. I’ve been optimizing that by pre-deciding to just write something down somewhere.

This removes a bunch of heuristics I’ve been using when writing notes or documentation:

“Does this feel generally useful?” Just write it down.

“Have I been asked this more than once?” Just write it down.

“Was I surprised by learning this?” Just write it down.

“What’s the best format to convey this?” I don’t know, you don’t know, just write it down.

The other optimizing rule I’ve been using is that it needs to be written down somewhere with a relatively permanent URL. This means that I’ve gotten a lot of use out of the docs.new domain shortcut to get an empty Google Doc.

Some of my stuff has turned out to be useless. But now, I don’t feel bad about “wasting” a minute to write it. If nothing else, I remember it better because of the mid-term memory benefits to writing something down at all. If Google Drive search ever starts being useful, maybe I’ll even be able to find it again 😛

Anyway, this has been an especially good practice for me as an on-call engineer. When I write something down that’s not immediately useless, I’ll link it to my team, and we’ll collaborate to make it better. And then the doc is definitely worth saving!