What a good handover document actually contains
We read a lot of handover documents. Some arrive with a system we are taking over, some we write when we hand one on, and a few arrive after the fact from a client asking whether the thing they were given is any good.
The pattern in the weak ones is consistent. They describe the architecture in careful detail: the services, the data stores, the queues, a diagram with boxes and arrows, an inventory of endpoints. It looks thorough. It took someone a week.
And it is the one part the next team can work out for themselves. Give a competent engineer the repository and two days, and they will produce a better diagram than the one in the document, because theirs will match what is actually deployed rather than what was intended eleven months ago.
What they cannot derive by reading is everything else, and that is the actual handover.
The test that tells you if a document is real
Give it to someone who has never seen the system, and ask them to deploy a one-line change to production without asking anyone a question.
Whatever they get stuck on is the gap. This takes an afternoon and finds more than any amount of reviewing the document against a template. Most first attempts fail on something nobody thought to write down: a manual step in the deploy, a credential that is stored only in one person's password manager, an environment variable whose absence produces a confusing error.
Seven sections are worth including. Everything else is optional.
1. What the system must guarantee, ranked
Start with the promises, ordered by how bad it would be to break each one.
A user can only see their own organisation's data. An invoice total always equals the sum of its lines. A deletion removes the record everywhere it was copied. The nightly export runs before eight in the morning or somebody is told.
This list is almost never written down anywhere, and the people who can produce it are usually not engineers. Twenty minutes with whoever runs the business gets you a ranking that no amount of code reading would produce. It becomes the guide the receiving team uses to decide what deserves attention this week and what can wait indefinitely.
Put it first, because every other section is easier to read once you know what matters.
2. Decisions, with the options that were rejected
This is the highest-value section and the one most often missing entirely.
Code records the choice that was made. It never records the three that were considered and dropped, which is exactly what the next team needs before they change anything. Without it, someone spends a month discovering that the obvious approach does not work, when a sentence would have told them.
The format is deliberately small. One paragraph per decision:
We queue outbound notifications instead of sending them inline because the provider rate-limits at twenty requests per second and a bulk import will exceed that. We tried inline sending with a retry and it produced duplicate messages under load.
That is thirty seconds to write and it prevents a genuinely expensive mistake. Write these while the work is happening, not at the end, because the rejected options are the first thing people forget. A document assembled in the final week is written by someone reconstructing their own past thinking, and it always reads more coherent than the reality was.
Include the decisions you are not proud of. "This was a deadline compromise and the right fix is X" is more useful than silence, and it stops the next engineer assuming the ugly part is essential.
3. How it has actually failed
Real incidents. Not a risk register.
What happened, what the symptom looked like, what it turned out to be, and what was changed afterwards. Three or four of these are worth more than any amount of hypothetical failure analysis, because they tell the reader where this specific system breaks easily rather than where systems in general break easily.
If it has never failed in production, say that, and describe the near misses from staging instead. An honest short section is better than a long one filled with guesses.
4. The runbook
The operational tasks, written as steps someone can follow at three in the morning without having to make a decision.
Deploy. Roll back. Rotate each credential. Restore from backup, including how to verify the restore worked. Respond to each alert that can fire, with what it means and what to check first.
Two tests for this section. First, has anyone other than the author actually followed it, start to finish? Unexecuted runbooks are reliably wrong in small ways that matter under pressure. Second, does any step require knowing something not written in the document? "Deploy as usual" is not a step.
The backup restore is worth calling out separately, because it is the one that is almost never tested and always assumed to work. A backup nobody has restored is only an assumption.
5. The unknowns, stated plainly
Every real system has parts nobody currently understands. A handover that omits them loses the receiving team's trust within a fortnight, because that is roughly how long it takes them to find the first one.
So write them: this module was inherited and we have not traced it, this scheduled job was set up by a person who has left, this configuration value was tuned empirically and we do not know why the current number works.
An admitted gap is information the next team can act on. A confident description that quietly guesses is worse than nothing, because it will be believed. We treat this section as a sign of a serious document rather than a weak one, and its absence from a long handover usually means somebody was writing to impress.
6. Access, completely
Every account, credential, domain registration, third-party service, cloud project, monitoring tool, error tracker, payment provider, and email sender.
For each: who owns it now, who should own it after, and what breaks if it lapses. Domain and certificate expiry belong here specifically, because they are the failure that stops a whole system for a reason nobody is monitoring.
This section is boring and it is the one that causes the most trouble when incomplete. The usual pattern is that ninety percent transfers cleanly and one obscure service was on a personal card. That gets discovered when it fails.
7. A first-week path
Finish with a specific, small, real task the receiving team should do first, and the exact route to production for it.
Not a refactor. A one-line fix, all the way through: build, review, deploy, observe, and roll back again. The purpose is to test the delivery pipeline rather than the code, and to convert the handover from a document into something that has been used.
Everything they get stuck on is a defect in the handover, and it appears during a calm week rather than during an incident. More on the receiving side of this in how to take over a codebase you did not write.
What changes when the code was generated
All of the above gets more important, for a reason worth being precise about.
Handover has always depended on an unwritten backup plan: if the document is incomplete, phone the person who wrote it. Generated codebases remove that. There is no author who knows the reasoning, and the reviewer who approved the work has moved on to something else.
The visual signs are lost too. In a hand-written codebase, messy areas show where the problems are. Inconsistent naming, a function doing four things, three styles in one file: these are signals a reader follows. Generated code applies the same clean style to the part that was carefully specified and the part that was invented from a plausible guess, so consistency stops being evidence of care and the reader loses their main way of telling deliberate from accidental.
That is why the decisions section matters so much here. It is the only remaining way to say "this is on purpose". The practical detail is in handing over AI-written software.
The checks are part of the document
Prose describes the guarantees. A check suite states them in a form that can be executed rather than interpreted, and it is the part of a handover that keeps working after everyone has forgotten the prose.
Two conditions on that. The suite has to be written from the specification rather than from the implementation, because a suite generated by reading the code asserts that the code does what it does and passes by construction. And it has to be demonstrably able to fail: break something deliberately, confirm the suite notices, and record that you did. A passing test suite that nobody has tried to break is exactly the kind of false confidence that makes a handover feel safer than it is. The failure modes are catalogued in when evals give false confidence, and adding checks to an inherited system is covered in adding evals to an existing codebase.
How to get the knowledge out of a person
One practical note, because this is where most handovers are lost.
Do not ask someone to write a document. People do not know what they know, and the deep knowledge is stored as habit rather than as prose. Interview them instead, with specific prompts, and write it up yourself.
What would you warn a new engineer about on day one? What do you always check first when something is wrong? What is the part you would never touch on a Friday? What do you know that is not written anywhere? What did we try that did not work?
That last question produces the best material, every time. An hour of this yields more than a week of someone staring at a blank template.
Thanks to the teams who let us read handovers that failed and explain where they got stuck. The gap was never a missing diagram. It was one sentence about why something was built that way, which nobody thought was worth writing.
A handover is not a description of the system. It is everything about the system that the system cannot tell you itself.
Related guide: Maintaining custom software.
