Member-only story
Infrastructure Documentation Best Practices: ADRs, Runbooks and Diagrams as Code
Infrastructure documentation has a reputation problem. It is written during calm periods, never updated during incidents, and discovered by the next on-call engineer to be months out of date at the worst possible moment — 3am with a production alert firing. The failure mode is so consistent that many teams have concluded that documentation does not work and have stopped trying, relying instead on tribal knowledge, Slack history, and the institutional memory of engineers who have been there longest.
The documentation that does work has three properties: it is close to the code it describes (a Mermaid diagram in the same repository as the service it describes), it is written for a specific audience at a specific moment (a runbook written for the on-call engineer who has never seen this alert before), and it is maintained by the same process that maintains the code (documentation changes are required in the same PR as code changes). Documentation that is separated from the system it describes, written for a generic audience, and maintained in a separate process inevitably becomes stale.
This guide covers four documentation practices that consistently survive contact with real engineering teams: Architecture Decision Records (ADRs) for capturing the reasoning behind technical decisions…
