Documentation that the next engineer will actually read

Short post · 1 min read

Five habits that keep runbooks and designs short, current and useful.

Share on LinkedIn

Most infrastructure documentation is written once and never read. The usual reasons are that it is too long, it is out of date, or nobody can find it. Here is how I try to avoid all three.

Say who it is for

Put the purpose and the reader at the top: "This runbook is for the on-call engineer restoring the file server." One sentence is enough, and it decides everything that follows.

Write runbooks as numbered steps

Each step says what to do, what you should see afterwards, and what to do if you do not. Add the rollback steps at the end of the same page, not in a different document.

Record the decision, not only the design

A high-level design shows what was built. The approach paper explains why that option was chosen over the others, in terms of technical fit, cost and timescale. The second document is the one people want two years later.

Keep it next to the work

Store documents where the team already works, and keep scripts and their notes together in Git. A document that sits beside the thing it describes gets updated. One in a distant folder does not.

Put a review date on every page

An out-of-date runbook is worse than none, because people trust it. A review date tells the reader how much to trust the page, and it gives you a reason to revisit it after every disaster recovery test.