Documentation That Survives You: The Bus-Factor Test
Here is the question this whole pillar has been building toward, and it is a slightly uncomfortable one. Suppose you vanished today — new job, lottery win, or the proverbial bus. Could someone competent but unfamiliar run your network using only what you have written down? Not run it brilliantly. Just keep it alive: respond to the outage, provision the new hire, find the password vault, know who to call.
For most networks the honest answer is no, and the reason is rarely that nothing was written. It is that the documentation quietly assumes its author. It lives somewhere only you would look, behind accounts only you hold. It uses language only you can decode, with no dates to say what is still true. Documentation like that is a diary, not a handover. The real audience for everything you write was never you. It is the person who does your job when you cannot. That group includes the colleague covering your vacation and your eventual successor. It also includes, six months from now, a version of you that has forgotten everything.
This guide is the capstone of the pillar. It covers the test that tells you whether your documentation actually works and the four survival requirements that go beyond content. It also covers the drill that proves it — the same way a restore proves a backup.
In this guide
- The bus factor, borrowed from software
- The four survival requirements
- The handover drill: documentation's restore test
- Wiring survival into daily work
- Writing for a stranger having a bad day
- The bus-factor scorecard
- The drill script
The bus factor, borrowed from software
Software teams have a grim little metric called the bus factor. How many people could be hit by a bus before the project can no longer continue? A project where one person holds all the critical knowledge has a bus factor of one — the scariest number in the metric. The concept transfers perfectly to IT operations. Ask it of your network: how many people can vanish before nobody can operate this? If you are a solo admin or the strongest member of a tiny team, the honest answer is usually one, and that one is you.
Organizations usually try to raise bus factor by hiring or cross-training, and both help. But both are slow, expensive, and outside a junior admin's control. Documentation is the one bus-factor raiser you can build alone, on no budget, starting this week. Written knowledge is the only kind that does not commute home with you every evening. And you do not need the bus to cash in. The same documentation is what makes a real vacation possible. That is why the planned-absence playbook in How a Solo IT Admin Takes a Real Vacation is this exact muscle, rehearsed on friendly terms. A vacation is a scheduled bus.
One myth is worth clearing away first, because it quietly sabotages this work: the idea that being irreplaceable is job security. Being the only person who understands the network does not protect your job — it imprisons it. You cannot take a real holiday, cannot be properly sick, and cannot be promoted, because operations cannot spare you. Meanwhile every emergency is yours alone, at any hour, forever. Raising your bus factor is not writing yourself out of a job. It is writing yourself out of the 3 AM phone calls. Every experienced admin who has done it will tell you which of the two arrangements feels like security.
The pillar's other guides cover what to write — the six-document kit, the diagrams, the labels. This guide's claim is that content is only half of survival. A perfect runbook can still fail its reader four different ways before they read a word of it. Those four ways are the survival requirements.
The four survival requirements
1. Where it lives: reachable when your infrastructure is down
A short horror story, told in every IT community with the details changed: the company wiki held everything — runbooks, diagrams, the credential guide. The wiki ran on a VM, on a host, behind the core switch. The core switch failed. The runbook for "core switch failure" was, at that moment, sealed inside the failure it described — the fire manual stored inside the burning building. Everyone involved now keeps printouts.
The rule: your documentation's availability must not depend on the thing it documents. Keep the working copy wherever it works best day to day. And keep a break-glass copy of the survival core: network map, access guide, top runbooks, key contacts. Put that copy somewhere that shares no fate with your network. This could be a printed folder in a known drawer, an export on an independent cloud service, or both. Refresh it on a calendar — quarterly is realistic — and date every page. A break-glass copy you cannot trust is just more paper. When you next update the kit described in Minimum Viable Network Documentation, the export is the last step.
2. Access that outlives you
The second failure mode is quieter and nastier: the documentation survives, but the keys do not. The domain registrar account under a personal email address. The vendor portal whose multi-factor prompt goes to a phone that left with its owner. The doc system whose only administrator no longer works here. Every inherited network carries scars like these. The landmine tour in Taking Over an Undocumented Network is full of them. Every one of those scars was created by a reasonable person taking the convenient path on a busy day.
The rule: no personal custody of organizational access. Registrars, certificate authorities, ISP and vendor portals, cloud tenancies, and the documentation system itself must be owned by role accounts (it-admin@company, not you@company, and never you@personal). Recovery paths must reach a monitored organizational mailbox. More than one person, or a documented break-glass method, must be able to satisfy multi-factor enrollment. Audit this once. List every external account the network depends on and ask "who could log in the day after I leave?" Then let the access guide's staff-change hook keep it true. This requirement is invisible right up until it is the only thing that matters.
3. Findability by a stranger
Documentation that exists but cannot be found by a newcomer does not exist. You navigate your docs by memory; a stranger navigates by what is visible, under stress, with no one to ask. Two fixes. First, create the entry-point document: one page, boringly named — START-HERE or README — in the most obvious location. It links to everything: the six documents, the monitoring console, the password vault process, and the break-glass folder's physical location. It also links to the two sentences of orientation a stranger needs ("this is a two-site network; the important closet is behind reception"). Everyone who might ever cover for you gets told where that one page is; it carries the rest. A workable skeleton:
START HERE - IT operations entry point (last verified: [date]) WHO TO CALL FIRST: [name / role, phone] THE NETWORK IN TWO LINES: two sites, one firewall at HQ, servers virtualized on two hosts in the HQ closet. 1. Network map ............... [link] 2. Device inventory .......... [link / monitoring console] 3. Address plan .............. [link] 4. Credential ACCESS guide ... [link] (passwords live in the vault) 5. Runbooks (outages) ........ [link] 6. Quirks file (read me!) .... [link] Break-glass printed copy: gray folder, second drawer, reception safe.
Second, use names that say what things are. A stranger scanning a folder must be able to guess contents from titles. For example, network-map-office.pdf beats final_v3_NEW.pdf in a way that decides outcomes at 2 AM.
4. Currency signals: the reader must know what to trust
A stranger cannot smell staleness the way you can. You know the diagram predates the firewall swap; they see a confident drawing. So every document declares its own age: a visible "last verified" date on the first line, updated whenever a human confirms the content still holds. This is why stale-but-dated beats fresh-looking-and-wrong. A page marked as verified two years ago correctly triggers caution, while an undated wrong page triggers confident action. Confident action on false information is how small outages become large ones. Dates also make neglect visible in the quarterly skim: a document nobody has verified in a year is raising its hand.
The handover drill: documentation's restore test
Admins learn early that a backup you have never restored from is a hope, not a backup. It is the same self-skepticism that has a whole pillar of its own in Who Watches the Watcher. Documentation deserves the identical discipline. Its restore test is the handover drill. A willing colleague sits down with your documentation and attempts five realistic tasks. They use only what is written. That colleague could be an IT-adjacent coworker, a fellow admin from another department, or anyone competent who does not share your memories. You watch, and you do not help. Every time they get stuck and you ache to blurt the answer, that ache is the drill working. The drill has found knowledge that lives in you and not on paper.
The five tasks cover the moments of need. Provision something (add a device or user the standard way). Respond to a mock outage using a runbook, dry-run style, narrating each step. Retrieve a credential's access path end to end (not the password itself — the path to it, break-glass included). Answer "what is this?" for an IP address you point at. And find the right vendor support number plus the account number they will demand. Score each pass/struggle/fail, and write the failures down as they happen. That list is your documentation backlog, ranked by demonstrated reality rather than guesswork. No colleague available? Role-play it cold yourself: pick a task, and follow only what is written, hands off everything the docs do not mention. Humbling, and nearly as effective.
Why a drill, when you could just re-read everything? Because reading and using are different tests, and only one of them is honest. When you review your own docs, your memory silently fills every gap. The page says "connect to the switch" and your brain supplies which switch, from where, over what. The drill removes the gap-filler. A stranger executing the steps has only the words on the page. So every unstated assumption becomes a visible stumble instead of an invisible one. This is exactly why restore tests find what backup-job green checkmarks miss: success is only provable by the consumer, never by the author.
Run the drill annually, plus after any major change — new core equipment, a migration, a documentation reorganization. It takes an hour or two, and it converts "I think a stranger could cope" into evidence. There is no other way to get that evidence short of the real emergency.
Tip: the drill doubles as quiet cross-training. The colleague who stumbled through your runbooks this year is measurably better prepared to cover your vacation next year. They have seen the docs, found the vault, and learned where START-HERE lives. Bus factor: raised, twice, for one afternoon.
Wiring survival into daily work
None of this survives as a heroic annual project. It survives as small hooks inside work you were doing anyway. That is the same living-system principle that runs through this whole pillar. The recap, assembled in one place. Change hooks: every change to topology, addressing, or procedure carries its documentation edit in the same sitting — diagrams, port descriptions, runbooks alike. Intake and outtake hooks: arrivals and retirements touch the inventory and address plan before the ticket closes; staff changes trigger the access-custody review within the week. Ownership: one name on every document, even if every name is yours — ambiguity, not laziness, is what kills maintenance in teams. The quarterly skim: half an hour with all six documents, verifying dates, chasing blanks and unknown tags, refreshing the break-glass export. The annual drill: the proof. Hooks keep documents true; the drill proves the system of documents works; the calendar keeps both honest. That is the entire machine, and it costs perhaps a day per year outside work you already owed. If you keep only one habit from this paragraph, keep the skim-plus-export pairing. A quarterly half hour that ends by refreshing the break-glass copy quietly satisfies half the scorecard below on its own.
Writing for a stranger having a bad day
The last requirement is tone, and it is the cheapest to fix. Your reader is not you-on-a-good-day. Design for the worst realistic reader: a capable person, unfamiliar with this network, mid-incident, adrenaline up, comprehension down. For that reader, write plain words instead of house jargon. Use "the switch in the ceiling above reception" with the formal name beside it, not instead of it. Write steps, not essays: numbered actions, one action per line, with what-you-should-see after the critical ones ("the console prompt changes to (config)#"). State locations physically ("second drawer, key on the red fob"). Spell out the recovery from the likely mistake, because the stranger will make it. And when you finish a page, run the panicked-stranger voice test. Read it aloud and ask whether a rattled newcomer could follow it verbatim, no improvisation required. Suppose you hear yourself adding spoken footnotes — "oh, and it only works from the management VLAN." In that case, the page is missing a line, and you just found it.
If writing for a hypothetical successor feels abstract, remember who actually collects first: you. Six months from now, the details of today's firewall migration will have evaporated from your head. Future-you is a stranger to present-you, just one with the same taste in coffee. Every kindness in the writing pays out: the dates, the plain words, the what-you-should-see lines. The payoff comes the very next time anything breaks and you cannot quite remember how you fixed it last time. Succession documentation is self-care with a delay.
The bus-factor scorecard
Score yourself honestly: 0 for "no", 1 for "partly", 2 for "yes, and it is current".
| Requirement | 0 points | 1 point | 2 points |
|---|---|---|---|
| Core documents exist (the six) | Little or nothing written | Some exist, gaps known | All six, drafted or better |
| Off-infrastructure copy | Docs live only inside the network | Partial or stale export | Dated break-glass copy, refreshed quarterly |
| Access custody | Key accounts personal or unknown | Audited, fixes pending | Role-owned, recovery paths verified |
| Entry point & naming | No START-HERE; cryptic names | Entry page exists, partial coverage | One page reaches everything; names self-explain |
| Currency signals | No dates anywhere | Some documents dated | Every document carries last-verified |
| Handover drill | Never run | Run once, findings pending | Run within the year, findings fixed |
Read the total in bands. 0–4: operations are one bad day from chaos. Start with the break-glass export and the access audit, this week, in that order. 5–8: survivable with bruises — a stranger would eventually cope. Close the cheapest gaps first (dates and START-HERE take an afternoon between them). 9–12: you pass the bus test. Your job is now maintenance, which the hooks and the calendar already handle. Re-score annually alongside the drill and keep the number somewhere visible. Watching it climb is one of the few genuinely satisfying metrics in IT.
The drill script
| Task | Tester may use | Pass looks like |
|---|---|---|
| Provision a new device the standard way | Inventory, address plan, conventions page | Right subnet chosen, address reserved, naming and description conventions followed |
| Respond to a mock outage ("file server is down") | Runbook, network map, monitoring console | Correct runbook found and narrated step by step without improvisation |
| Retrieve a credential's access path | Access guide | Vault located, break-glass path explained, no password written in the docs themselves |
| Answer "what is this address?" for an IP you pick | Address plan, inventory | Subnet, purpose, and owning device identified in under five minutes |
| Find vendor support for the internet circuit | Access guide, quirks file | Right number, account identifier, and any support PIN in hand |
Where to go next
The bus-factor test is the standard the whole pillar answers to. The six-document kit gives a stranger the content. The diagrams and auto-maps give them the picture. The labels meet them in the closet. The four requirements plus the drill make sure all of it is actually reachable, readable, and true on the day it is needed. Work through the rest of Network Documentation & Topology Mapping in any order. Score yourself today, and let the number tell you where to start.
Put this into practice with SysPeep Monitor
Part of surviving you is a console a stranger can read. SysPeep Monitor keeps an auto-discovered inventory, live dashboards, and network maps. These show what exists and what is healthy without needing anyone's memory. SysPeep Monitor's alerts can go to a shared mailbox, not a person. One more thing that keeps working when you are away. The free trial installs on any Windows machine.
Download Free TrialLearn About SysPeep