Somebody Else's Hands: Proving Your Network Documentation Actually Works

There is a particular kind of discomfort that settles over an administrator when a network fault resolves itself just as the household or the office empties. The link comes back, the router reboots cleanly, and everyone assumes the problem is closed. In practice, nothing has been learned and nothing has been written down. The next failure will be diagnosed from scratch, by whoever happens to be present — and that person may not be the one who built the network.

Small networks in the UK, whether a four-rack home lab in a spare room or a twelve-desk office above a shop, tend to accumulate undocumented decisions. A VLAN added for a smart television, a static lease granted to a printer during a hurried afternoon, an altnet ONT replaced under warranty with a different model number. Each is trivial in isolation. Together they form a knowledge base that exists in exactly one place: somebody's memory.

Why a wiki page does not solve this

The instinctive response is to write it up. That instinct is correct, but the usual output — a page on a self-hosted wiki, last edited fourteen months ago, seeded with a diagram exported from a drawing tool — tends to fail in the moment it is needed. It fails because it was written by the person who already knows the answers, for an audience of themselves, and because it has never been read by anyone who did not already understand it.

A handover pack is a different artefact. Its purpose is not to record knowledge but to transfer it. That distinction changes what goes inside, how it is written, and critically, whether it is tested.

The contents of a pack that earns its place

A workable dossier for a small UK network can be assembled in a single evening. What matters is coverage rather than polish, and there are eight components worth including as a minimum.

• A topology diagram. Physical and logical, drawn separately. Copper and fibre runs on one page; VLANs, subnets and gateways on another. Neither needs to be beautiful, but both need labels that match reality.
• A port map. Every switch port, patch panel position and wall socket, labelled with the device that occupies it and the room it serves. Photographs of the rack, taken with the labelling legible, are a legitimate substitute for a spreadsheet.
• ISP and altnet contacts. Account numbers, circuit references, support telephone numbers and the escalation path. For full-fibre premises, the ONT serial and the wholesale network operator's details matter as much as the retail provider's.
• A VLAN and DHCP map. Address ranges, gateway addresses, which SSID maps to which VLAN, and the reason each VLAN exists. Static leases should be listed with the device and the reason it was pinned.
• Configuration backups. Router and switch exports, dated, stored somewhere reachable without the network itself. A copy on the NAS that the failed network serves is not a backup.
• Credential handling. Not passwords in the document, but a clear statement of where they live and how to reach the vault, plus a sealed envelope or offline record for the one account that gates everything else.
• A plain-English recovery checklist. This is the heart of the pack.
• A change log. A short, dated list of what altered and why. Three lines per entry is sufficient.

Writing a checklist for someone who is not you

The recovery checklist is where most packs quietly fail. It is usually written in the vocabulary of the person who built the system, and it assumes a mental model that a newcomer does not hold.

The test is simple to state: could a competent IT generalist who has never seen this network follow the document to restore basic connectivity, without calling you? If the answer is uncertain, the checklist needs work.

Start from the most likely failure and work outwards. Loss of internet with the LAN intact. Loss of both. A single VLAN unreachable. The ONT showing a red status indicator. Each scenario becomes a numbered sequence, beginning with what to observe rather than what to do, and each step states the expected result so that the reader can tell whether it worked.

Avoid the phrase 'log in to the router' without saying which address, which interface, and which account. Avoid naming a device by the hostname only you use for it. Where a decision depends on information held elsewhere, say where.

The drill: handing it over

The value of the pack is established by testing it, not by writing it. Pick an evening, choose someone with general technical competence but no familiarity with this network — a colleague, a friend who administers systems elsewhere, a household member who is comfortable with a terminal — and arrange a controlled simulation.

The drill itself need not be elaborate. Bring the WAN link down at the router, or power off a core switch, and hand over the folder. Then observe, and say nothing else. Nobody learns anything from a test where the author leans over and supplies the missing step.

Record three things: the time taken to restore service, the number of points at which the reader paused or asked a question, and the exact words that caused confusion. That third item is the most valuable output of the exercise. It is almost always a small thing — an ambiguous label, a stale IP address, an assumption about which port is the uplink — and it is almost never something the author would have found alone.

A second drill, run a few months later with a different person, is worth more than any single successful test. It confirms that the corrections were actually made to the document rather than to the author's memory.

Keeping the pack alive

The failure mode of all documentation is drift. The network changes, the folder does not. The remedy is not discipline in the abstract but a habit attached to an existing action: whenever a change is made to the network, the change log gets a line, and if the change affects topology, addressing or credentials, the relevant page is updated before the job is closed.

An annual review is sensible, but so is a lightweight one: check the ISP contact numbers and the firmware versions once a quarter, and confirm that the configuration backups are recent and readable. A pack that is ninety per cent accurate is useful. A pack that is confidently out of date is worse than none, because it will be trusted.

None of this requires budget. It requires a folder, a printer, and the willingness to hand your own work to somebody else and watch where they stumble. The 3am call may never come. If it does, the difference between a difficult hour and a straightforward one will have been settled months earlier, in a document nobody thought they would need.