The traditional handover document is written in the last week of a project by whoever has the least to do, from memory, about decisions taken four months earlier. It is sixty pages, it is read once by nobody, and the first real incident is handled by calling the agency anyway.
We changed two things about how we produce it. Neither is clever; both worked.
Write it during, not after
Every runbook entry is written the first time the thing happens, not at the end. The deploy procedure is written the first time we deploy. The "what to do when the payment webhook retries" note is written the first time it retries, by the person debugging it, while they still remember which log line mattered.
This costs about ten minutes each time and produces a document that is accurate, because it was written by someone who had the problem in front of them rather than someone reconstructing it.
It also fails safely. If a project ends early or the budget shifts, the documentation that exists is the documentation for the parts that were built, which is the correct subset. A handover written at the end has no partial state — it is either done or absent.
Put the first page first
Most handover documents open with architecture. Architecture is the third thing someone needs. When a person opens this document, something is usually wrong, and they are usually not the person who built it.
Our first page is one side of A4 and answers, in this order:
How do I know it is broken? Where the alerts go, what the dashboard is, what normal looks like on it.
What do I do in the first five minutes? Restart what, check what, and what not to touch. Explicitly: which action is safe to take while still unsure.
What are the three things that have actually gone wrong before? With the symptom, the cause and the fix. Real incidents, not imagined ones.
Who do I call, and when is that reasonable? Names, hours, and — importantly — permission to call. People sit on incidents for hours because nobody told them escalating was allowed.
Where is everything? Repo, hosting, database, DNS, secrets, monitoring, domain registrar. One list of links, kept current.
Architecture, data model and decision records follow. They are important, and they are reference material rather than emergency material.
The test
A handover document is not done when it is written. It is done when someone who did not build the system uses it to do something real.
So before we close a project, someone from the client's team performs a deploy from the document, with us watching and not helping. Every question they have to ask out loud is a gap, and we fix the document rather than answering the question.
That exercise has never once been passed on the first attempt. It usually surfaces three or four assumptions so embedded that nobody thought to write them down — which is precisely the category of thing that makes a 2am incident take four hours instead of twenty minutes.
Why we bother
Partly because it is the right thing to hand over. Mostly for a more selfish reason: it makes us honest. A system that cannot be explained in a page is usually a system that is more complicated than it needed to be, and writing the page is the fastest way to find that out while there is still time to simplify.