Keeping system documentation and network diagrams current

Reference article · 5 min read

Most agencies have documentation. What they often lack is documentation anyone trusts on a bad day. Network diagrams drawn two refreshes ago, a server spreadsheet that predates the last virtualization project, three versions of the same rack layout with nothing to indicate which is current. The material exists, but it cannot be relied on, so staff work from memory instead, and that memory belongs to two or three people.

That is the real exposure, and it is usually what an IT director is trying to fix when a long-tenured administrator gives notice. The answer is not more documentation. It is a deliberately small set, each item with a named owner, a defined update trigger, and a location a successor or consultant would find without being told.

The set worth maintaining

Resist the urge to document everything. Aim for what a competent stranger would need to keep the lights on and make a change safely.

Network and rack diagrams. One logical diagram showing segments, VLANs, routing boundaries, firewalls, and external connections. One rack elevation per closet and data room showing what is mounted where, what it plugs into, and which circuit and switch port it uses. Two views kept separate beat one crowded drawing.
A one-page profile for each system. Purpose, business owner, technical owner, hosting location, version, dependencies, integration points, recovery expectations, support contact with the contract or ticket path, and renewal date. Note on the page whether the system supports a statutory function or handles regulated data.
Credential and license records, in a vault. Service accounts, shared administrative credentials, certificates and their expiration dates, license keys, and entitlement counts. These belong in a secrets vault with role-based access and an audit trail, never in a document or a diagram's notes field.
As-built notes from projects. What was actually installed and configured at the end of a project, including deviations from the design and work deliberately left for a later phase.

Add runbooks for the few systems that must come back first after an outage. Beyond that, extra documents decay faster than they earn their keep.

Where each piece lives

Findability matters as much as accuracy. Pick one location per artifact type and publish the map.

Diagrams belong in a versioned repository or document library, exported to a viewable format so people without the drawing tool can read them. System profiles work well as pages in the wiki or service management platform the help desk already uses, linked from the configuration item so a technician reading a ticket lands on the profile. Credentials live in the vault only. As-built notes attach to the project record and link from the affected profiles.

Write down the map itself: a short index naming each artifact, its owner, its location, and its update trigger. That index is the first thing you hand a new hire or consultant.

Triggers, not calendars

Annual review cycles fail because nothing during the year forces the work. Attach updates to events that already happen.

Change tickets. A change touching topology, addressing, ports, or integrations does not close until the affected diagram or profile is updated. Make it a checklist item on the change record and have the approver verify it.
Project closeout. No final acceptance until as-builts, updated diagrams, and revised profiles are delivered and reviewed by agency staff, not merely submitted.
Contract and license renewal. Renewal is a natural moment to confirm owner, support path, entitlement counts, and next renewal date.
Personnel change. When someone leaves a role, their named ownerships move to a successor before their last day.
Assessment findings. Security assessments and continuity exercises surface undocumented dependencies. Feed those back into the profiles, not only a corrective action plan.

Reducing the bus factor deliberately

Documentation reduces key-person risk only when someone other than the author tests it.

Run a read-only walkthrough. Give a staff member who does not administer a system its profile and diagram, then ask how traffic reaches it, who to call, and how it is restored. Every question they cannot answer from the page is a gap.

Schedule handoffs before they are urgent. When a senior administrator announces retirement, use the notice period for walkthroughs of the systems only they touch, with the successor writing the notes. Recordings help, but they are not a substitute for a page someone can search.

What to require of vendors and integrators

Documentation obligations are cheap to write into a solicitation and expensive to negotiate afterward.

Name the deliverables: logical and physical diagrams, interface descriptions, as-built configuration, and a support escalation path with hours and response expectations.
Require an editable source format, not only a PDF, so staff can maintain the drawing after the vendor leaves.
Tie acceptance or a portion of final payment to delivery and agency review of those documents.
Require documentation updates as part of any change the vendor performs during the maintenance term.
State that the agency owns the documentation describing its own environment and that it survives the contract.

During evaluation, ask candidates how they hand off documentation at the end of an engagement, and what the agency receives if the relationship ends early.

How to start

Do not launch a documentation project. Start with the systems that would hurt most: pick the few supporting statutory or public safety functions, write a one-page profile for each, and draw one current logical network diagram. Confirm both with the people who operate them. Then attach the triggers, assign owners by name, and let the set grow only when an incident or audit shows it must.

HQT provides systems engineering and technology advisory services to state and local agencies, including documenting existing environments and defining documentation deliverables for solicitations and closeout.

Frequently asked questions

What IT documentation should a small government agency actually maintain?

A small set is more useful than a large one: a logical network diagram, rack elevations for each closet and data room, a one-page profile for each system naming owners and support contacts, credential and license records held in a secrets vault, and as-built notes from completed projects. Runbooks for the systems that must be restored first after an outage are a reasonable addition. Anything beyond that tends to go stale before it is ever read. Each item should have a named owner and one agreed storage location.

How often should network diagrams be updated?

Tie updates to events rather than to a calendar date. Any change that alters topology, addressing, ports, firewall rules, or integrations should require the diagram to be updated before the change ticket closes, and project closeout should require updated as-built drawings before final acceptance. A periodic review still has value as a backstop, but on its own it usually produces a rushed annual cleanup instead of current drawings.

Should passwords and license keys be stored in the system documentation?

No. Credentials, service account details, certificates, and license keys belong in a secrets vault or password manager with role-based access and an audit trail, not in documents, spreadsheets, or the notes field of a diagram. The system profile should point to where the credentials are held and who can authorize access, without containing the secrets themselves. Keep at least one break-glass access path that does not depend on a single employee.

What documentation should we require from a vendor in a contract?

Name the deliverables explicitly: logical and physical diagrams, interface and integration descriptions, as-built configuration, and a support escalation path with hours and response expectations. Require editable source files rather than only PDFs so staff can maintain the drawings later, tie acceptance or a portion of final payment to agency review of those deliverables, and require updates whenever the vendor makes a change during the maintenance term. Also state that the agency owns documentation describing its own environment and that ownership survives the contract.

How do we reduce key-person risk before a senior administrator retires?

Use the notice period for structured walkthroughs of the systems only that person touches, with the successor writing the notes rather than the departing employee. Then test the result by handing the profile and diagram to someone who does not administer the system and asking them to explain how it works, who to call, and how it is restored. Gaps they cannot close from the page are the items worth documenting next.