Documenting your network: diagrams, IPAM and the spreadsheet that will not die

Every network has a spreadsheet. Mine, at the help desk I used to run, was called something like "IP addresses FINAL v3", and three people kept their own copies of it. I am not going to tell you to throw yours away. A spreadsheet that someone actually maintains is better than a perfect system nobody opens. What I will do is help you decide what belongs in your documentation, when the spreadsheet has done its job, and how to keep the whole thing true after the first enthusiastic week.

The test for every page is the same: could a colleague who has never seen this network use it at 3 a.m. to find a device, an address or a phone number? If yes, it is good documentation, whatever tool it lives in.

What to write down

Five things, in roughly this order of value. For each one there is a list of minimum fields. Start with those and add more only when someone asks for them.

The IP plan

Every subnet, what it is for, and who hands out its addresses.

• Prefix and site
• VLAN ID
• Purpose in plain words
• Default gateway
• DHCP range, and which server or device runs DHCP
• Static range and what lives in it
• Notes (firewall zone, "internet only", anything surprising)

A small office might look like this:

When you plan new ranges, the subnet calculator will save you from the classic mistake of a mask that does not quite cover what you thought it did.

VLANs

• VLAN ID and name
• Purpose and the subnet it carries
• Which switches and trunks it is allowed on
• Which wireless network (SSID) maps to it, if any
• The native VLAN on each trunk, written down explicitly

Small networks get the same benefit as large ones here. The reasoning behind separating devices into VLANs is laid out well in VLANs at home, and the same table works for an office.

Circuits

Circuits are the thing you need to know about least often and most urgently.

• Provider and circuit ID, copied exactly as written on the provider's label or contract
• Service type and bandwidth
• Both ends, with the demarc location (building, room, rack, port)
• Handoff type (single-mode fiber with LC connectors, copper RJ45, and so on)
• Addresses assigned by the provider
• How to open a fault ticket: where the support number is kept and which account reference to quote
• Contract end date

The circuit ID matters more than anything else on that list. It is the first thing the provider's support desk will ask for, and it is never on the sticker you can see from the doorway.

Device inventory

• Hostname and role
• Model and serial number
• Software version
• Management IP address
• Location: site, room, rack and rack unit
• Power: which PDU or UPS feeds it
• Support or warranty end date

Do not type serial numbers by hand if you can help it. Most managed devices report them over SNMP in the ENTITY-MIB:

snmpwalk -v3 -l authPriv -u nms-ro -a SHA -A "$SNMP_AUTH" -x AES -X "$SNMP_PRIV" \
  10.20.99.11 ENTITY-MIB::entPhysicalSerialNum

Where credentials live, never the credentials themselves

Documentation gets copied, exported, printed and pasted into tickets. Passwords do not belong in it. What belongs in it is the location: "Core switch local admin account: team password vault, folder Network / Core." SNMP community strings and SNMPv3 keys count as credentials too (if you are still on community strings, SNMP v1, v2c and v3 explains why that is worth changing). Also write down the break-glass plan: who can get into the vault when the vault itself, or the network it runs on, is down.

IPAM: is the spreadsheet still enough?

For one site, a few hundred addresses and one or two people editing, a well-kept spreadsheet is fine. These are the signs it has stopped being fine:

1. Two people have edited it at the same time and one set of changes vanished.
2. You find the same address listed twice, or a device on the network that is not listed at all.
3. People ping an address before using it because they do not trust the "free" column.
4. Nobody knows which copy is the current one.

When those start happening, a dedicated IP address management tool earns its keep. Two open-source options come up again and again. NetBox describes itself as a source of truth for network infrastructure. It covers IP addressing (prefixes, addresses, VLANs, VRFs) and also the physical side: sites, racks, devices, interfaces, cables, circuits and providers, all reachable through an API. phpIPAM is narrower and lighter. It concentrates on subnets and addresses, and it can scan subnets to find which addresses are actually in use. Both are self-hosted.

A rough way to choose: if your main pain is addresses, phpIPAM is often enough. If you also want racks, cables and circuits in one place, NetBox fits better. Either way, clean up the spreadsheet before you import anything. A tool will faithfully preserve every mistake you feed it.

Diagrams: physical and logical

One diagram cannot answer every question, so draw a few, each with one job.

If your diagramming tool supports layers (draw.io and Visio both do), keep the physical drawing as the base and put the VLAN and routing views on layers you can switch on and off. That keeps device positions consistent between views, which helps people more than you would expect.

A few rules make any diagram more useful:

• Every device shows its hostname and management address.
• Every link shows the port name at both ends.
• There is a legend, a date and an owner in one corner.
• The editable source file sits next to the exported image, in the same folder, with the same name.

Keeping it fresh

Documentation is never finished. The aim is to make it decay slowly and get corrected quickly.

Tie it to the change process

No change is closed until the documentation it touches has been updated. One line in the change template does most of the work: "Docs updated: link, or the reason none were needed." The same rule keeps runbooks honest, which matters because a runbook is only as good as the hostnames and ports it relies on.

Let the monitoring system check your work

Your NMS already talks to every managed device on a schedule. Use it to compare what is documented with what is real.

• Devices the NMS polls but the inventory does not list, and the other way round.
• LLDP or CDP neighbor tables compared with the links on your diagram. With the LLDP-MIB file loaded, snmpwalk against LLDP-MIB::lldpRemSysName lists each neighbor a switch can see.
• ARP tables from routers and MAC address tables from switches compared with the IPAM, to find addresses in use that are marked free.
• Serial numbers and software versions read over SNMP, compared with the inventory.

Auto-discovery has its own pitfalls (it happily adds every printer and phone), and the field manual page on organizing monitored hosts covers how to keep it under control. For finding which switch port a device sits on, a dedicated tool such as Netdisco does this well by collecting those same MAC and neighbor tables.

Walk it

Once a quarter, take one closet's diagram to the closet and check it against the rack. It takes half an hour and finds things no discovery tool will, like the unmanaged switch under someone's desk.

Date everything

Put a "last verified" date and a name on each page. A page that says "verified 2026-08-30" earns trust. A page with no date earns a ping test.

A starter checklist

If you are starting from nothing, or from one tired spreadsheet, work through this in order. Each item is small enough for one sitting.

This week:

1. Pick one place for documentation and tell everyone where it is.
2. List every subnet with its VLAN, gateway and DHCP range.
3. List every circuit with the provider's circuit ID and how to open a fault ticket.
4. Write down where credentials are kept, and the break-glass plan.

This month:

5. Build the device inventory, pulling serials and versions over SNMP where you can.
6. Draw the overview diagram and the physical diagram for the main site.
7. Add "Docs updated" to the change template.
8. Put a "last verified" date on every page you have so far.

This quarter:

9. Draw the layer 2 and layer 3 diagrams.
10. Compare the NMS device list, neighbor tables and ARP tables with your documentation, and fix what differs.
11. Decide whether the spreadsheet is still enough, using the four warning signs above.
12. Walk one closet with its diagram in hand.

Twelve small steps, and at the end of them the new colleague at 3 a.m. can find what they need. That is the whole point.