When the Only Copy Lives in Someone's Head: Five Documentation Habits That Prevent Engineering Hostage Situations
Photo: Ndahiro derrick, CC BY 4.0, via Wikimedia Commons
Every IT leader can name the person. The one who gets called at 2 a.m. when the billing batch fails. The only human being who knows why the legacy ERP integration breaks every quarter-end. The engineer whose two-week vacation is treated, half-jokingly, as a business continuity risk.
The joke stops being funny when the resignation letter lands. In the US labor market, where median tenure for tech professionals hovers around three years, institutional knowledge walking out the door is not a hypothetical — it is a scheduling certainty. What separates resilient organizations from hostage situations is not headcount or budget. It is a handful of documentation habits, none of which require new tooling, and all of which can begin this quarter.
Habit One: Write Runbooks for the 2 A.M. Version of Yourself
The failure scenario: a payment processing outage at 1 a.m. The on-call engineer finds a wiki page last updated in 2019 that says, in its entirety, "restart the service and check the logs." Which service? Which logs? What does a healthy log line look like?
Resilient teams write runbooks for a reader who is stressed, sleep-deprived, and has never touched the system before. That means: exact commands, expected outputs, decision points phrased as if/then logic, and an explicit escalation threshold — "if X persists after 15 minutes, page Y." A useful test: hand the runbook to an engineer from an unrelated team and see whether they can execute it. If they cannot, the document is a memory aid, not a runbook.
Habit Two: Treat Offboarding as a Documentation Deadline, Not an Exit Interview
The failure scenario: a senior database administrator gives four weeks' notice. Everyone spends those weeks on knowledge-transfer meetings — which produce three hours of rambling video nobody ever watches. Six months later, a replication failure occurs, and the team discovers the one workaround the DBA knew exists only in a recording nobody can search.
Resilient organizations invert the process. When notice is given, they ask the departing engineer to spend their final weeks writing, not talking: updating the runbooks they own, annotating the cron jobs only they understand, and documenting the three workarounds they have never written down. Talking is a supplement. Writing is the deliverable. And critically, the review of that documentation is assigned to a named successor, who signs off that they can operate from it.
Habit Three: Make Documentation a Definition of Done
The failure scenario: a new microservice ships to production with a beautiful README — generated by the scaffolding template and containing no real information. Six months of incident retrospectives later, the team keeps rediscovering the same behaviors.
The habit is procedural, not aspirational: a pull request is not done until its documentation is done. Service ownership pages, configuration flags, and operational quirks get updated in the same merge as the code. Teams that resist this as overhead should price the alternative — the average major incident burns dozens of engineering hours, and undocumented systems reliably extend every one of them.
Habit Four: Keep a Single, Searchable Source of Truth
The failure scenario: the answer to "how do we provision a vendor VPN account" exists in four places — a Confluence page from 2021, a stale Slack thread, a PDF in someone's downloads folder, and the actual current process, which lives in one senior engineer's head. Three of the four are wrong, and nobody knows which three.
Scattered documentation is functionally equivalent to no documentation, because readers cannot tell which version is authoritative. Resilient teams consolidate aggressively: one system of record per domain, clear ownership on every page, and a standing rule that outdated documents are archived or deleted rather than left to mislead. A wrong runbook is more dangerous than a missing one.
Habit Five: Rotate the Burden — and the Knowledge
The failure scenario: the same engineer has written every runbook for the payments platform for three years. The documentation is excellent. It is also a single point of failure with a keyboard, because no one else has ever exercised it, and the writer's mental model has drifted far past what the pages say.
Documentation that is never read is documentation that is already rotting. Resilient teams rotate runbook ownership quarterly and run lightweight game days where an engineer who did not write the runbook must execute it under time pressure. Every gap they hit becomes a fix; every fix keeps the document honest. This converts documentation from a museum exhibit into living operational infrastructure.
Start This Quarter
None of these habits requires a platform purchase or a transformation program. The sequence is simple: inventory your single points of failure by name, prioritize the systems where a departure would cause real business impact, and apply the five habits there first. The hostage situation you prevent will be invisible — and that is precisely the point.
