Short answer
#The split that works
| Facts about the system | Decisions and habits | |
|---|---|---|
| Examples | Components, dependencies, endpoints, data flows, scheduled work | Why this design, what was rejected, what breaks regularly, what to check after a deploy |
| Where it lives | In the system | In people |
| Best method | Derive it | Ask specific written questions |
| Cost by hand | Days to weeks, and incomplete | An hour, if the questions are good |
| Can it be checked? | Yes, if it carries citations | No — it is testimony |
| Window | Open indefinitely | Closes when they stop replying |
Almost every bad handover gets this backwards: it spends the closing window on the column that stays open, and produces a document about the system rather than about the decisions.
#What to derive
These are properties of the code and can be established by anybody with access to it, at any time, including after everybody has left:
- The components the system is made of, with a readable purpose for each.
- What depends on what, and in which direction.
- The interfaces it exposes and consumes, and roughly what each operation does.
- The data it holds and where that data moves.
- What runs on a schedule.
- And — the part hand-written documentation never contains — an explicit list of what could not be established.
The last item is what makes a derived picture more useful than a written one for a handover specifically. A hand-written document has gaps and does not know where they are. A derived one turns each gap into a question you can put to the outgoing team while they are still there.
#What must be written by a person
Six things, none of which any analysis will ever recover, in rough order of value:
-
What you would be nervous about somebody changing, and why
The highest-value paragraph in any handover document. It is short, specific, and impossible to derive.
-
What was tried and abandoned
Stops the new team spending a quarter rediscovering that an approach does not work here.
-
What is here because of a constraint that no longer exists
The other half: stops them keeping something that could now be removed, or removing something that is load-bearing.
-
What breaks regularly, and what you do about it
The operational runbook, written as what actually happens rather than as procedure.
-
Which alerts matter and which are noise
Without this a new team either ignores everything or investigates everything.
-
What has to be done by hand, and when
Monthly and quarterly manual steps are discovered in month three, by their absence.
#How to specify it in a contract
"Documentation and knowledge transfer" is unenforceable, because there is no state of the world in which it is either complete or incomplete. Replace it with deliverables that have a truth value:
On termination the Supplier shall deliver:
1. Written answers to a list of questions supplied by the Client
at least 15 working days before the end of the engagement.
The Client may supply up to 25 questions.
2. A demonstration week in which the Client's incoming team,
unaided, (a) runs the system locally from the written setup
instructions, (b) deploys a change to production, (c) rolls
that change back, and (d) restores a backup into a scratch
environment. The Supplier shall be available to advise.
3. A list of everything that runs and is not in the repository.
4. A list of every external service the system depends on, with
the account holder of each.
Acceptance: the engagement is complete when the incoming team
has (a) deployed unaided, (b) restored a backup, and (c) answered
ten questions about the system, chosen by the Client, correctly
and in writing.Every line here is checkable, and none of it requires anybody to judge whether a document is "good enough". Both sides benefit: the supplier knows exactly what finishes the engagement.
#The shape of a document that gets read
If a person is going to write something, three properties decide whether it is ever read again:
- Short. Six paragraphs that are read beat sixty pages that are not. A handover document nobody finishes is worth nothing.
- Answers rather than sections. Written as replies to specific questions, not as a document with an imagined structure. The questions give it an order somebody else can navigate.
- Dated and attributed. A claim about a system, with no date and no name, cannot be weighed by the person who finds it two years later.
#What goes wrong
Asking for “full documentation of the system”.
Instead Ask twenty-five specific questions. Unbounded requests produce unbounded anxiety and a document written to look complete.
Having the outgoing team write an architecture overview.
Instead Derive it. Their remaining hours are the only source in the world for the other column.
Accepting a recorded walkthrough as the deliverable.
Instead Better than nothing, worse than written answers: nobody rewatches two hours, nobody can search it, and the person who needs it has not been hired.
Writing it once and never dating it.
Instead Date and attribute every part. A handover document is read years later by people who need to know how much to trust it.
Producing documentation that cannot be checked.
Instead Where a statement is a fact about the system, it should point at where it came from. Where it is testimony, it should say whose.
#What this does not cover
What this does not do
- Product documentation for users. Different audience, different problem.
- API documentation for external consumers, which is a published artefact rather than a handover one.
- Compliance documentation, which has a defined form somebody else specifies.
- The question of who maintains any of it afterwards — which is a real question and is the reason a derived picture is worth more than a written one over time.