Documentation for the engineer who replaces us

Write for a stranger

Every project we deliver ends with a handover, and we write it assuming the person reading it a year from now has no memory of this conversation and no access to us. That constraint is the single most useful discipline for producing documentation that actually gets used instead of documentation that gets written to satisfy a deliverable checklist and then ignored.

We split handover documentation into three distinct artifacts, because conflating them is the most common reason documentation fails: a README that answers "what is this and how do I run it," a runbook that answers "it's 2am and something is broken, what do I do," and architectural decision records that answer "why does this work this way and not some other way." Each one has a different reader, a different moment of use, and a different shelf life.

The README

The README is the one most teams get right instinctively: setup instructions, environment variables, how to run tests, how to deploy. Where it usually falls short is currency — a README that was accurate at launch and never touched again is worse than no README, because it actively misleads the next engineer with confidence. We treat README accuracy as a release gate, not a one-time deliverable: if a change to the deploy process ships, the README changes in the same pull request.

The runbook

The runbook is the one teams underinvest in, and it is the one that matters most during an actual incident. A good runbook does not explain the system's architecture — that is not what someone reads at 2am. It gives a decision tree: this alert fired, here is what it usually means, here is the first thing to check, here is the command to run, here is who to escalate to. We write runbooks against actual incidents we have handled during the engagement, not hypothetical ones.

Decision records

Architectural decision records are the one most teams skip entirely, and the one that saves the most time downstream. A short, dated note — we chose a queue-based architecture over synchronous calls here because of this specific throughput requirement — prevents the next engineer from spending a week reverse-engineering a decision, concluding it looks wrong, and re-litigating it. We write these throughout the engagement, because the reasoning is sharpest when the decision is fresh.

The honest caveat

No amount of documentation substitutes for a system that did not need to be that complicated in the first place. The best handover document is often a short one, because the underlying architecture is straightforward enough that a competent engineer can read the code and understand it without much narration. We treat an unusually long runbook as a signal to go back and simplify the system, not just as a documentation task to finish.

If you have inherited a system with documentation that does not match reality — or you are planning ahead for a handover you know is coming — we can help you build the version of this that actually gets used. Get in touch and we'll start with an audit of what exists today.