When to start writing the runbook

The mistake

The runbook always gets written under duress. Three weeks after launch, when oncall is paging someone for the third time at 2am.

The fix

We start the runbook in week one. It’s a single markdown file in the repo. Every “oh by the way” the team learns goes in. Every undocumented config var goes in. Every workaround goes in with a date and a name.

By launch, the runbook is 60% there. By month two, the on-call rotation can use it without paging the senior engineer who wrote the code.

Writing it during the build feels like overhead. Not writing it during the build is a future tax.