Minimum Viable Network Documentation
Somewhere in your organization there is probably a documentation wiki. It has eleven pages. Three are empty except for a heading, one is a lunch menu from a vendor event, and the newest edit is older than your job. Everyone agrees documentation is important, the way everyone agrees flossing is important. And yet here you are, tracing a mystery cable at 7 PM, because the only person who knew what it did no longer works here.
Here is the uncomfortable truth: that sad wiki beats having nothing by less than you would think. Network documentation almost never fails because people are lazy. It fails because the project was too ambitious — a forty-section template, a diagram of every cable, a policy for the policies. Maximalist documentation collapses under its own maintenance cost, goes stale, and stale documentation is worse than none, because it lies to you with a straight face.
The fix is not more discipline. The fix is a deliberately small set of documents. Each is chosen because it answers a question you will genuinely ask under pressure. Each is kept true because keeping six things true is actually possible. This guide gives you that set. It covers what each document is for, roughly what goes in it, what it costs to maintain, and how to bootstrap the whole kit in one honest afternoon.
In this guide
- Why documentation fails by trying too hard
- The six documents that matter
- Why these six: the moments-of-need test
- The one-afternoon bootstrap
- Maintenance that actually happens
- Format: searchable beats beautiful
- The starter kit on one page
Why documentation fails by trying too hard
Every failed documentation effort follows the same arc. It starts after an incident, with real enthusiasm. Someone builds a beautiful structure: categories, templates, naming standards. For two weeks, pages appear. Then real work interrupts, the structure demands more effort than anyone has, and the project quietly dies — leaving behind just enough content to be misleading. Two years later, a new admin reads a confidently written page about a firewall that was replaced eighteen months ago and acts on it. The admin learns to distrust every page in the system. That distrust is the real damage. Documentation only works if people reach for it first, and they only reach for it if it has earned trust.
Minimum viable documentation borrows its logic from the minimum viable product idea in software. Build the smallest thing that genuinely works, then improve it only where reality demands it. For network documentation, "genuinely works" means one thing. When something breaks, when something new arrives, or when someone new takes over, the answer they need is written down, findable in under a minute, and true. Six documents can meet that bar. Sixty cannot, because you will not maintain sixty, and one stale page poisons trust in the other fifty-nine.
The six documents that matter
Here is the whole kit. Each entry tells you the question the document answers and gives a sketch of its contents. It also gives the honest maintenance cost, because a document you cannot afford to maintain is a document you should not create.
1. The network map
One page that shows how traffic flows: internet connection, firewall, core switch, the switches behind it, servers, wireless. Not every cable and desktop — the skeleton. Its job is to let someone reason about the network during an outage: "if this box is down, everything behind it is down too." A useful map fits on one screen or one sheet of paper, carries a date, and marks unknowns honestly with a question mark. Drawing maps people actually use is its own craft, with its own guide: Network Diagrams People Actually Use. Maintenance cost: minutes per topology change, which for most small networks means a few edits a year.
2. The device inventory
This is the list of what you own: every switch, router, firewall, server, access point, UPS, and anything else with a management interface. Each entry has a name, IP address, model, location, and role. This is the register every other document points into, and the rest of this pillar assumes it exists. If it does not yet, start with Building a Device Inventory You Can Trust, because an inventory built by scanning the network beats one built from memory every time. Maintenance cost: near zero if your monitoring or discovery tool maintains it for you; one row of edits per device added or retired if you keep it by hand.
3. The address plan
This is the record of your IP space. It shows which subnets exist, what each is for, which VLAN it maps to, and where the gateway is. It also shows which ranges DHCP hands out versus which are reserved for static assignment. A subnet is a block of addresses that belong together. A VLAN is the switch-level segment that usually carries it. And the address plan is where those facts stop living only in the router's configuration. It answers "what is this address?" and "where does the new server go?" — two questions that come up constantly. The full craft of writing one down lives in Documenting Your Address Space. Maintenance cost: an edit per new subnet or scope change; rare by nature.
4. The credential and access guide
This one is misunderstood, so read carefully: it is the document that says where credentials live and how to get access. And it must never contain the passwords themselves. Passwords belong in a proper password vault (a purpose-built encrypted store), or at minimum in a sealed break-glass envelope in a safe. The access guide is the pointer layer above all that. For each system, it says where its credential is kept and what the emergency path is if the normal one fails. That might be the console cable and local account, the second admin account, or the vendor phone number plus the account number they will ask for. A sketch:
SYSTEM WHERE THE CREDENTIAL LIVES EMERGENCY ACCESS Core switch Vault > Network folder Console cable; local account (vault) Firewall Vault > Network folder Break-glass envelope in office safe Domain admin Vault > Windows folder Second break-glass admin account ISP support Vault > Vendors (account no.) Phone + account number + support PIN
Why it earns its slot: the worst hour to discover that nobody knows how to reach the firewall is the hour the firewall is misbehaving. Maintenance cost: one line per new system, one review whenever staff change.
5. The critical-services runbook set
A runbook is a written procedure for handling one specific situation: symptoms, steps in order, how to verify the fix, and who to call if it does not work. You do not need fifty. You need one for each of the five emergencies most likely to actually happen to you. Typically that is some mix of "internet is down," "server X is down," "phones are down," "nobody can log in," and "restore a file from backup." Written for a reader having a bad day: short sentences, exact commands, no essays. Writing good ones is a whole discipline of its own — the Runbooks pillar covers it — but five imperfect runbooks today beat a perfect library someday. Maintenance cost: a re-read after each real incident, updating whatever the incident proved wrong.
6. The quirks file
Every network accumulates knowledge that fits no schema. There is the switch that needs ten minutes after a power loss before you should worry. There is the vendor portal registered under an email address of someone who left. There is the one conference-room port that was disabled on purpose and must stay that way. Today that knowledge lives in your head, which is a single point of failure with vacation days. The quirks file is institutional memory's junk drawer. And it is deliberately informal: dated freeform entries, appended as surprises happen, never reorganized into a taxonomy. Example entries:
## Warehouse switch (SW-WH-01) Needs ~10 minutes to come back after power loss. Do not power-cycle it again "because it seems stuck" - it is booting. ## ISP portal login Registered under bob@oldcompany-address - Bob left years ago. Credential location: vault, under "ISP - legacy login". ## Port 14 on the floor-2 switch Disabled on purpose (loop incident with an unmanaged switch someone brought in). Leave it disabled.
Maintenance cost: thirty seconds per surprise. It is the cheapest document on this list and, for whoever inherits your network, quite possibly the most valuable.
Why these six: the moments-of-need test
This list is not arbitrary. Each document maps to a recurring moment of need — a situation that reliably happens to every network and demands a written answer. An outage needs the map (what depends on the broken thing?), the runbooks (what do I do?), and often the quirks file (is this actually normal?). Provisioning — adding a device, a subnet, a service — needs the inventory and the address plan. A lockout or emergency access problem needs the credential guide. And a handover, planned or sudden, needs all six at once. Outage, provisioning, lockout, handover: four moments, six documents, full coverage.
The test also tells you when to add a seventh document, and more importantly when not to. Before creating any new document, name the recurring moment of need it serves. "It would be nice to have" is not a moment of need. "Every time the auditor visits we scramble to answer the same questions" is — and if that happens to you yearly, an audit-answers document has earned a slot. A document without a moment attached is a report someone wanted once, and it will decay into exactly the kind of stale page that poisons trust in the rest.
Notice what fails the test at this stage. End-user how-to guides fail it (a different library with a different audience). So do formal policy documents (worth having, but they serve governance, not operations). And so does anything that duplicates what a tool already renders on demand. When a system can show you a live answer — current interface status, say — documenting a snapshot of it just creates a page that is wrong by Tuesday. Document the things only a human knows; let machines report the things machines know.
The one-afternoon bootstrap
The trap at this point is planning a Documentation Project, which is how we got the sad wiki. Instead, block one afternoon and build the whole kit at draft quality, mostly by promoting things that already exist into official status.
- Hour one — map and inventory. If a monitoring or discovery tool already scans your network, its device list is document two. In that case, export it or simply declare the tool's inventory page the official register. The tool's topology view is the skeleton of document one; screenshot it, print it, and annotate by hand. If nothing has ever scanned your network, a short discovery pass fixes that and feeds both documents at once — the discovery sprint shows exactly how.
- Hour two — address plan. Your router and DHCP server already know the answer. Pull the subnet list from routing configuration and the scope list from DHCP, paste into a table, and add a one-line purpose for each subnet. Where you do not know the purpose, write exactly that.
- Hour three — access guide and runbook stubs. Write the credential-location table for your ten most important systems. Then create five runbook stubs: title, symptoms, and your best current answer, even if the best current answer is three bullet points and a phone number.
- Hour four — quirks file. Open a blank page and write down every landmine you currently carry in your head. Most admins surprise themselves by filling a page in twenty minutes. That page is the one your successor would have paid the most for.
Throughout, follow the honest-gaps rule: where you do not know something, write unknown rather than leaving the field out. This matters more than it looks. A search for "unknown" later gives you a ready-made to-do list, and a reader who hits "gateway: unknown" knows to verify before acting. An omission does neither — unknowns are findable, omissions are invisible. Documentation that admits ignorance stays trustworthy; documentation that hides it does not.
Tip: resist the urge to polish anything during the bootstrap afternoon. Draft quality across all six documents is worth far more than perfection on two of them, because coverage is what gets you through the next incident. Polish later, one document at a time, when a real use reveals what actually needs improving.
Maintenance that actually happens
Now the part that determines whether this kit is alive in a year. The core principle: documentation does not get updated as an act of virtue. Nobody ever has a free Friday for it, and "keep docs updated" as a standing intention fails everywhere it is tried. Documentation gets updated when the update is a step inside a workflow that was happening anyway.
Concretely, that means three hooks. The intake hook: when a new device or subnet or service arrives, the last step of setting it up is touching the affected documents. That means a row in the inventory, a line in the address plan, and a credential pointer. The outtake hook: when something is decommissioned, same thing in reverse. A retired server that lives on in the docs is a small lie that compounds. The change hook: when you change topology or a critical procedure, the map or runbook edit rides along as part of the change. Do it in the same sitting while the details are still in your head. Each hook costs a minute or two. If your team uses any kind of change checklist or ticket template, write the hook into it so it survives busy weeks and new hires.
Hooks catch what you change on purpose. For everything that drifts anyway, add the quarterly skim. That is half an hour, four times a year, reading all six documents with fresh eyes and a cup of coffee. You are not rewriting — you are marking. Anything stale gets fixed on the spot if it takes under two minutes, or flagged with a dated note if it takes longer. And give every document an owner — one name, stated at the top. In a team, ownership prevents the everyone-assumed-someone-else effect. If you are an IT department of one, you own all six, and the quarterly calendar reminder is your co-owner.
Format: searchable beats beautiful
Admins lose weeks to the question of where documentation should live, so here are the only three properties that matter, in order. First, searchable: at 2 AM, mid-outage, you will not browse a folder tree — you will type a device name into a search box. Plain text and simple wiki pages win here; a binder of gorgeous PDFs loses. Second, one home: pick a single place — a wiki, a shared folder, whatever your organization already uses — and put all six documents there. Use a plain index page linking to each. Two homes means every reader must check both and trust neither. Third, exportable: your documentation must survive the death of the thing it documents. If the wiki lives on a server behind the switch that just failed, your runbook is locked inside the patient. Keep a periodically refreshed break-glass copy of at least the map, the access guide, and the runbooks. Keep it printed or stored somewhere that shares no infrastructure with your network. Making documentation survive failures and departures is a deep enough subject that it gets its own guide: Documentation That Survives You.
Notice what is not on the list: beautiful. A plain page that is true and findable beats a polished page that is either stale or lost. Spend your scarce minutes on truth, not typography.
The starter kit on one page
| Document | Answers | Template fields | Update trigger |
|---|---|---|---|
| Network map | How does traffic flow? What depends on what? | Core path, key devices, uplinks, date + author, question marks on unknowns | Any topology change |
| Device inventory | What do we own, where, and what is its address? | Name, IP, model, serial, location, role | Device added or retired |
| Address plan | What is this subnet for? Where does the next thing go? | Subnet, VLAN, purpose, gateway, DHCP range, static range | Subnet or scope change |
| Access guide | Where do credentials live? What is the emergency path? | System, credential location, break-glass path | New system; staff change |
| Runbook set | It broke — what exactly do I do? | Symptoms, steps, verification, escalation contact | After every real incident |
| Quirks file | Why is it like this? | Dated freeform entries | Every surprise, same day |
Where to go next
Six documents, four moments of need, one bootstrap afternoon, and a maintenance system made of hooks instead of good intentions — that is minimum viable network documentation. From here, deepen whichever piece your network leans on most. The drawing craft is in Network Diagrams People Actually Use. The automation angle is in Auto-Generated Topology Maps. The physical layer is in Labels, Port Descriptions, and Cable Hygiene. The final exam is in Documentation That Survives You. The rest of the Network Documentation & Topology Mapping pillar ties the set together.
Put this into practice with SysPeep Monitor
Two of the six documents can largely maintain themselves. SysPeep Monitor auto-discovers the devices and interfaces on your network, keeps a live inventory, and draws network maps that stay current as things change. That gives you a working draft of your map and register from day one. The free trial installs on any Windows machine.
Download Free TrialLearn About SysPeep