Writing

As built documentation for networks

Published 22 September 2026

The design is not the as-built. The design says what was meant to be installed. The as-built says what actually got installed, and the gap between the two is where the next outage lives, because everyone troubleshooting at 2am is reading the wrong one.

A note on terms first, because the search results disagree with each other. Most of what is written about as built documentation is about buildings: the as built drawings a contractor marks up and hands over when the concrete has cured. That is a real discipline and it is not this one. This is about network and IT infrastructure: switches, patch panels, VLANs, addressing, firmware, circuits. The idea transfers cleanly. The practice does not, because a building stops changing and a network does not.

What actually diverges

Nobody sets out to deviate from the design. Deviation is what an install looks like when it meets the room. A typical cutover produces a handful of these, none of them dramatic:

Every one of those is defensible. Every one of them is invisible six months later. The last row is the classic: a temporary fix that became permanent because it worked, and because the only person who knew it was temporary has moved on. The design document still says the route was removed, which is worse than saying nothing, because someone will believe it.

Why as-builts rot immediately

The honest answer is not laziness. It is sequencing. The information exists at exactly one moment: during the cutover, in the head of the person with a torch in their teeth, and the documentation is scheduled for a moment when it no longer does.

"We'll update the drawings after" fails for a reason that is structural rather than moral. After the cutover there is no window, no ticket, no budget code and no pressure; the network is up, which is the only outcome anyone was measuring. Meanwhile the details decay fast. The port number is gone in a week. The reason for the port number is gone by the end of the night.

So the window is the cutover itself. Not the week after, not the handover meeting. Capture is a task on the night's runsheet, with a name against it, or it does not happen.

What to capture at cutover, while it is still true

The test for each item is simple: would you have to go and look at the hardware to recover this? If yes, write it down now. If it can be pulled from a running device in thirty seconds whenever you like, it is lower priority and possibly not your job.

• Actual port assignments. Device, interface, what is on the other end, and which patch panel port it lands on. Both ends. A record of one end is half a record.
• Actual addressing. Management addresses, VLAN IDs and names, subnets, gateways, any static routes or ACLs added on the night. What is configured, not what was allocated.
• Firmware and software versions as shipped. Including the ones you meant to upgrade and did not.
• Serial numbers, and where the thing physically is. Building, room, rack, rack unit. A serial without a location is a warranty record, not documentation.
• Circuit identifiers and the provider's contact path. The circuit ID is the only thing the carrier's support desk will accept at 2am, and it is on a piece of paper in the comms room.
• What deviated from the plan, and why. Both halves.
• Photographs of the rack before you close it: front, rear, and the patch panel. Thirty seconds, and they answer questions nobody has thought to ask yet.
• Labelling as installed. Not the labelling scheme: the labels that are actually on the hardware, including the two that were hand-written because the printer ran out.

Labelling, and being precise about the standard

If someone tells you the labelling follows TIA-606, be clear about what that does and does not mean. ANSI/TIA-606 is the administration standard for telecommunications infrastructure: it defines identifier schemes and labelling for cables, terminations, pathways, spaces and grounding, and the records that go with them. It tells you how to name things consistently. It does not tell you what was installed on the night, and it is not a substitute for capturing it.

The practical point is smaller than the standard. Record the labels that are physically on the equipment, exactly as they read, even where they are wrong. The next person is going to read the label, not your scheme.

Who this is for

Worth being concrete, because the audience determines the detail level and most as-builts are written for nobody in particular:

• The person doing the next change. They need to know what is really connected where before they take something out of service. They are the most frequent reader by a wide margin.
• The person on the outage call at 2am. They need the circuit ID, the management address, the rack location and the name of whoever the contract says to ring. Under time pressure, half-remembered.
• The auditor. They need to see that what is deployed matches what was approved, and where it does not, that the divergence was recorded rather than discovered.
• The engineer who inherits it when you leave. They get whatever you wrote down and nothing else. This is the one worth writing for, because it is the only case where you cannot be asked a follow-up question.

How much is too much

A document nobody maintains is worse than no document, because it is confidently wrong. An empty wiki page makes someone go and look at the rack. A detailed wiki page from 2023 makes them act on it.

That is the whole argument for restraint. Every field you add is a field that has to be right forever, and the ones that go stale fastest are the ones that were most satisfying to fill in: a full port map of a 48-port switch where twelve ports are in use, cable lengths, transceiver part numbers, a diagram with every patch lead drawn.

The minimum that survives, in practice:

1. What is in each rack, and where in it.
2. What connects to what, at least for uplinks, routed links and anything crossing a boundary.
3. Addressing and VLANs as configured.
4. Deviations from design, with reasons and dates.
5. Who to ring for each circuit and each vendor.

Five things. If you are arguing about the sixth, you have probably found the line. Anything that can be generated from the devices themselves (running configurations, MAC tables and neighbour discovery output) should be generated, not transcribed, because transcribed data is stale the moment it is typed and nobody trusts it afterwards.

As-built, network documentation, and a diagram

These get used interchangeably and they are three different artefacts with three different lifecycles.

The as-built is a snapshot with a date on it, and its value comes from being frozen: it is evidence of what happened on a particular night. Network documentation is a living description, and a series of as-builts is the raw material that keeps it honest. Treating the as-built as something to keep editing is how it quietly becomes a bad copy of the running configuration.

A diagram is not documentation. It is an index to it. A diagram is genuinely good at conveying topology, which is why inside a data center network is largely a description of shapes, and genuinely bad at holding a port number, a serial, a firmware version or a reason. Diagrams also rot silently: a spine-and-leaf drawing stays plausible long after it stops being accurate, because the shape is still right and only the detail is wrong. Draw the diagram. Do not let it be the only thing you have.

Where it lives matters as much as what is in it

The most common failure is not a missing document. It is a document nobody can find: a PDF in a share, a page in a wiki that three people have editing rights to, a photograph in someone's camera roll, a paragraph in a closed ticket. When the as-built lives somewhere other than the project it describes, finding it costs more than rediscovering the fact, so people rediscover the fact, and the document ages another year.

The low-tech version works: one folder per project, named for the site and the date, with the photographs in it. It beats a wiki page that was accurate once.

The thing to take away

Capture is a cutover task, not a follow-up task. Write down what was installed and why it differed from the plan while the person who decided it is still standing in the room. Keep it small enough to stay true, date it, and store it with the project rather than near it.

The next outage will be caused by something that was changed on a night like that, by someone reasonable, for a good reason. Whether it takes ten minutes or four hours to find depends entirely on whether anyone wrote the reason down.