The handover doc has a table of contents. Numbered sections. Clear headings. Every command is correct. Every configuration value is documented. Every architecture diagram is current.
It is also impossible to use.
Not because it’s wrong. Because what you need to know isn’t in it. Which rules are real and which are performance. Which choices were made for reasons that still apply and which were made because someone wanted to go home. The doc is accurate the way compiled output is accurate. It contains every instruction. It contains none of the reasoning.
The deployment rule.
The doc says: deploy from the jumpbox. Do not deploy from a laptop.
It doesn’t say what the jumpbox is for. It doesn’t say someone deployed from a laptop in 2019 and the deploy script had an unset environment variable and production went down for four hours while the team figured out which version of which dependency wasn’t on the laptop. It doesn’t say the postmortem for that incident had seven action items and the jumpbox was the only one that shipped. It doesn’t say the engineer who pushed for a proper CI pipeline was told it was a Q3 item and Q3 never came.
The rule is in the doc. The scar isn’t.
The next engineer reads the rule and deploys from the jumpbox. Two years later the jumpbox is the only machine still running an unsupported operating system and nobody knows why it exists or whether it’s safe to touch. The rule survived. The reason for the rule didn’t.
The architecture choice.
The doc says: services communicate over gRPC.
It doesn’t say two senior engineers argued about this for a month. It doesn’t say one wanted REST with explicit versioning and the other wanted gRPC for performance, and the REST advocate left partly over it. It doesn’t say the gRPC advocate still thinks it was the right call and will explain why if you ask – which nobody does, because the doc says gRPC and the doc is treated as fact.
The choice is documented. The argument isn’t.
The next engineer who questions the choice – and someone will, because every engineer who inherits a system questions a decision – has no way to know the counterarguments were already made. They reopen the debate in good faith and step into a wound they didn’t know existed. If it goes badly, they learn the argument through social friction. If it goes well, they get a lunch explanation from the engineer who stayed. Either way, the doc couldn’t help. The format doesn’t have a field for who lost and why.
The on-call threshold.
The doc says: if queue depth exceeds 1000, page the infra team.
It doesn’t say the threshold was set by a manager who wanted fewer pages. It doesn’t say the infra team resents being paged for a queue that isn’t their service and a root cause they can’t fix. It doesn’t say the actual practice is to clear the queue manually at 900 and not tell anyone, because paging creates more problems than it solves.
The documented rule and the real practice have diverged. The doc records the rule. It doesn’t record the practice. The new engineer follows the rule once – pages infra at 1001 – and learns the real rule through someone’s irritated response. The next new engineer will make the same mistake for the same reason. The practice is known by everyone and written down by nobody. The doc is correct and misleading. It can’t be any other way.
The gap.
The handover doc is not incompetent. The engineer who wrote it knew these things: the 2019 outage, the gRPC argument, the shadow practice. They left them out. Partly because nobody writes a handover doc that includes the arguments - by the time you’re writing one, you’re already leaving. Partly because a document that tried to include them would not be a handover doc. It would be an oral history, and the departing engineer had two weeks.
What’s lost is not random. It’s a specific class of information: why the rule exists, not just what the rule is. Who argued for and against a decision. What incident created a threshold. Which practice everyone follows and which practice everyone says they follow.
This is what a compiler does. It keeps the instructions and discards the comments. The machine doesn’t need comments to execute. It needs them to modify. The debug symbols are gone when the people leave: who carries which subsystem, who knows the queue’s history, who remembers the gRPC argument. The build context is invisible once the moment passes: the deadline that forced a shortcut, the manager who wanted fewer pages, the compromise that shaped the decision. The team delivers the binary. The future can run it. It can’t read it.
The doc becomes scripture.
The handover doc arrives with the weight of apparent completeness. Table of contents, numbered sections, clear headings. It looks authoritative. It is authoritative. The commands work. The diagrams are correct. The thresholds are real. Nobody questions it because questioning requires knowing what’s missing, and what’s missing is exactly what the doc doesn’t tell you.
The doc becomes scripture not because it was written as scripture. Because it’s the only artifact the team has, and the alternative is discovering every scar through the incident that would have explained it. That’s expensive. Reading the doc is free. The team reads the doc and follows the rules and doesn’t ask why. Asking why has a cost. Following has none – until the system changes in a way the rules don’t account for. Then nobody knows which rules are load-bearing.
What’s different at team scale.
An incident report loses context: why the mechanism failed, in what order, what fixed it. A handover doc loses something different. It loses rationale. Why the decision exists at all.
Context tells you how to prevent a failure from recurring. Rationale tells you which decisions you can revisit and which ones you can’t. Without rationale, every decision is load-bearing. You can’t remove the jumpbox because you don’t know whether removing it brings back the 2019 outage. You can’t change gRPC to REST because you don’t know whether the arguments against REST were about performance or politics. You can’t adjust the queue threshold because you don’t know whether the threshold is a safety margin or a managerial compromise.
The system calcifies. Not because the decisions were wrong. Because they’re unreadable.
The messier case.
The handover doc is the clean case: someone leaves, they write it down, the binary is produced at a known moment. The messier case is the codebase convention nobody remembers the origin of: the config value with the comment that just says “do not change,” the deployment order that everyone follows and nobody questions. Knowledge doesn’t exit. It fossilizes. The artifact records what to do. It doesn’t record whether the reason still applies. The pattern is the same. The decay is gradual.
What survives.
On teams where institutional memory survives, there’s a second artifact. It’s less formal than the handover doc. It’s more durable than oral history.
It records who made the call and why: not just what was decided, but who decided it, when, under what constraints, and who argued the other way.
gRPC, chosen March 2020. Advocated by A after B pushed for versioned REST. The disagreement was about whether performance mattered more than readability. A won the argument. B left six months later – not solely over this, but it contributed. Revisit if performance stops being the bottleneck.
It records scars: rules and thresholds that exist because of a specific incident. The incident is attached, so the next person knows what the rule is guarding and when the guard is no longer needed.
Deploy from jumpbox only. See INC-2019-047. Laptop deploy carried wrong dependency version. Postmortem had seven action items. The jumpbox was the only one shipped. The CI pipeline was a Q3 item that never became a Q3 project. If the CI pipeline ships, the jumpbox dissolves.
It records shadow structure: the rules everyone follows and the rules everyone says they follow. Not to fix the gap - just to acknowledge it exists, so the next engineer doesn’t learn it through someone’s irritated response.
Queue threshold: documented 1000 (audit requirement). We clear at 900 because paging at 1000 creates cascading alerts. The root cause is in the upstream service. Infra can’t fix it. They clear the queue. If the upstream service gets fixed, lower the threshold.
The second artifact is hard to keep because it requires admitting the documented rules aren’t the real rules. It requires writing down that the deployment rule is a monument to an outage from six years ago, that the architecture choice was won by the person who stayed, that the on-call threshold is a compromise with a manager who left. Teams that can admit this keep the source. Teams that can’t keep the handover docs and lose the memory.
The handover doc is the compiled binary. The source is the team that wrote it – and the team that wrote it is already gone.