Network Documentation and Labelling That Survives
Network documentation is the thing everyone agrees is important and nobody has time for, until an incident makes tracing a cable by hand the only option. The work is small; the payoff arrives concentrated at the worst moment.
Label both ends, always
The single highest-value habit, and it has to be done at installation because retrofitting means tracing everything.
Every cable, at both ends, stating what it connects and to which port. A cable labelled at one end only requires tracing to find the other, which is the work the label was meant to avoid.
The same applies to power cables: which PDU and which outlet. During an incident, powering off the wrong thing makes matters considerably worse, and our PDU guide covers why outlet labelling matters on switched units.
Labels need to survive years in a warm rack. Paper with a wax ribbon does not; polyester with a resin ribbon does. Our media guide covers the pairing, and a label that has fallen off or faded is documentation that has quietly stopped existing.
Adopt a naming convention and stick to it
Consistency matters more than cleverness.
A convention should identify the site, the room or rack, the position, and the device. It should be readable by someone unfamiliar with the estate, and it should be the same string everywhere — on the physical label, in the asset register, in monitoring and in the device’s own hostname.
That last point is the one that gets missed. When the label, the monitoring alert and the configuration all use different names for the same device, an incident becomes a translation exercise.
Avoid conventions that encode things which change — department names, project names, owner names. Location and function are stable; organisational structure is not.
What to record beyond cables
Documentation that answers questions rather than listing assets.
Port assignments. Which switch port serves which device or room, and which VLAN it belongs to. Our segmentation guide covers why VLAN documentation matters — an undocumented segmented network is considerably harder to troubleshoot than a flat one.
Addressing. Static addresses and reservations, particularly for printers and other network devices where an address change breaks every client configured against it.
Uplinks and dependencies. What connects to what, and what fails if a particular link goes down.
Firmware and configuration versions, so you know whether you are in a tested combination when something misbehaves. Our firmware guide covers why.
Out-of-band access details — console server ports, management addresses, and how to reach them. Our out-of-band guide covers what this is for.
Photographs do a lot of work
Faster than notes and more reliable, because they capture things nobody thought to write down.
Photograph the front and rear of each rack after any significant change. During a relocation this is what determines how long the outage lasts, and the same applies to any rebuild after a failure.
Date them and store them with the documentation rather than on someone’s phone.
Store it where it will be available
The failure that makes all the other work pointless.
Documentation stored only on the systems it documents is unavailable exactly when needed. A runbook on a server that is down, or credentials in a system behind the firewall you are trying to reach, may as well not exist.
Keep a copy that survives the loss of the infrastructure — off site, or offline, or both. The same applies to backup runbooks and encryption keys, and it is one of the most common recovery failures there is.
A printed copy in the rack sounds old-fashioned and is occasionally the thing that works.
Keep it current or it becomes harmful
Documentation that is wrong is worse than none, because people act on it.
Two habits keep it honest. Update at the point of change rather than afterwards — a change that includes updating documentation as a step gets done, one that leaves it for later does not. And verify periodically by spot-checking a few entries against reality.
When something is decommissioned, remove it. An asset register listing equipment that no longer exists produces wasted time and audit findings — our decommissioning guide covers this.
Where to start if you have none
Do not attempt to document everything at once; it will not finish.
Start with what an incident needs: rack photographs, power cable labelling, uplink and dependency mapping, out-of-band access details, and where the documentation itself lives.
Then label cables opportunistically — every time you touch one, label both ends. Within a year most of the estate is covered without a project.
Common questions
Why label both ends of a cable?
Because a cable labelled at one end still requires tracing to find the other, which is exactly the work the label was meant to avoid. The same applies to power cables, where powering off the wrong outlet during an incident makes matters worse.
What media should rack labels use?
Polyester with a resin ribbon. They need to survive years in a warm rack, and paper with a wax ribbon does not. A faded or detached label is documentation that has quietly stopped existing.
What makes a good naming convention?
Site, room or rack, position and device — readable by someone unfamiliar with the estate, and identical across the physical label, asset register, monitoring and hostname. Avoid encoding things that change, such as department or project names.
Where should documentation be stored?
Somewhere that survives the loss of the infrastructure it documents. A runbook on a server that is down, or credentials behind the firewall you are trying to reach, may as well not exist. A printed copy in the rack occasionally is the thing that works.
Where do I start if I have no documentation?
With what an incident needs: rack photographs, power cable labelling, uplink and dependency mapping, and out-of-band access details. Then label cables opportunistically whenever you touch one — within a year most of the estate is covered without a project.
Label both ends whenever you touch a cable — within a year most of the estate is documented without a project.
