What a real handover contains
A complete handover has four components. Most handovers have one or two.
The component that is almost always missing is the failure documentation. Most handovers cover what the system does. Very few cover what to do when it stops doing it.
01
What it does, in plain language
One to two pages describing what the system does, what triggers it, what it produces, and what it depends on. Written for someone who understands the business context but was not involved in the build. Not a code walkthrough - a description of behaviour. The test: can someone who reads this document explain to a colleague what the system does and why it exists, without asking the builder?
02
What it depends on
A list of every external dependency: APIs it calls, data sources it reads, services it writes to, credentials it uses, schedules it runs on. For each dependency, note what happens to the system if that dependency is unavailable. This list is the most important thing to have during an incident, because the first question in any failure is usually "what changed?" and the answer is usually "something this system depended on."
03
What breaks and how to diagnose it
A failure guide covering the three to five most likely failures, what each looks like from the outside, and what to check first. This does not need to cover every possible failure - it needs to cover the ones that are most likely based on what the builder knows about the system's weak points. A failure guide written by the builder takes thirty minutes to write and saves hours of diagnostic work the first time something goes wrong.
04
What routine changes look like
A description of the changes most likely to be needed after launch: updating a threshold, adding a recipient, adjusting a schedule, adding a new record type. Routine changes should be makeable by the operator without consulting the builder. If they require the builder to be consulted, either the documentation is incomplete or the system was not designed for maintainability. Both are fixable, but they need to be fixed before the builder steps away.
The test
A handover is finished when the operator can fix the common failure without calling you.
The builder knows how the system works; the Friday-afternoon operator does not, and has no time to acquire it. They need the shortest path from symptom to resolution, and most handover documentation is not written with that person in mind.
What gets handed over
The operator sees this, not the builder's code.
Testing the handover
The handover is not complete until the operator can demonstrate they can operate the system.
A handover session where the builder demonstrates the system to the operator is not the same as a handover session where the operator operates the system while the builder watches. The difference matters because the knowledge that feels transferred in the first case often is not - until the operator has to retrieve it under pressure, they do not know what they know.
The handover test
What the operator should be able to do before the builder leaves
Describe what the system does without referring to the documentation.
Identify where to look first if the system appears to have stopped working.
Make a routine change - updating a value, adding a recipient, adjusting a schedule - without asking for help.
Locate the credentials or access required to make changes if needed.
Identify who to contact if a problem is beyond their ability to resolve.
Common questions
Questions about system handover
Four things: the logic documented in plain language, failures that are visible and diagnosable without the original builder, named ownership for every part of the system, and the ability to make normal operational changes without calling the person who built it. If any of these four are missing, the system has a hidden dependency on the builder that will surface at the worst possible time.
Write for the moment when something goes wrong at 5pm on a Friday, not for normal operation. The most useful documentation answers three questions: what does this system do, what are the most likely failures and how are they diagnosed, and what is the fastest path to getting it running again if it stops. Exhaustive documentation that nobody reads under pressure is less useful than targeted documentation written for the failure cases that will actually occur.
For a well-scoped operational system, a proper handover should take one to two days of focused work, half for completing the documentation and failure-case testing, half for a walkthrough with the new owner. Systems that require more than two days to hand over properly are either underdocumented or were never built with maintainability in mind. The handover is the test of whether the build was finished, not a separate phase after the build.
