Should I use diagrams as code or a drawing tool for network diagrams?

Diagrams as code fits when the diagram describes something that changes and can be collected from the network, such as topology, dependencies, or a protocol exchange. A drawing tool is the better choice for rack elevations, cable runs, and floor plans, where position on the page corresponds to position in the physical world, and for a polished one-time deliverable made for an audience. Most teams run both, and the split follows whether the picture has to stay true over time.

What are the disadvantages of diagrams as code?

There are three real disadvantages. You give up layout control, because the engine decides placement and your only lever is link length and grouping. Readability falls off past roughly forty nodes, so large networks have to be split into several diagrams. And your teammates have to be willing to edit text, which is a change in working habit that some teams will not make.

Can diagrams as code handle a rack elevation?

Not well. A rack elevation is a picture where vertical position means rack unit and adjacency means physically next to each other. A layout engine places nodes to minimize edge crossings, so it will move a device that has to stay in slot 14. Rack elevations belong in a drawing tool, or in a tool that generates them from an inventory with explicit coordinates.

How many devices can one Mermaid diagram show?

Readability starts falling off around forty nodes and is usually gone by eighty, because the layout engine optimizes for edge crossings rather than the mental model you have of the network. Split by site, by tier, or by function before you hit that, and link the diagrams together. A complete diagram that nobody opens is not useful, however accurate it is.

Do I have to replace my existing diagrams?

No. Trying to replace everything at once is how the conversion stalls. Generate one diagram that is currently wrong and painful, usually the topology, and leave the rest alone. If the generated one stays accurate for a quarter without anyone maintaining it, converting the next one is easy to justify.

TRANSLATION

Diagrams as code or a drawing tool: when each one wins

Generated text diagrams stay accurate when the network underneath keeps changing. Drawing tools matter when position on the page carries meaning, or when the diagram only needs to be drawn once for an audience. Most teams need both, and the split is predictable.

Reading this, you will:

Decide which of your existing diagrams should become generated text.
Recognize the three costs of diagrams as code before you commit a team to it.
Split a large topology so a layout engine produces something readable.

What decides this is whether the diagram has to stay true to something that changes.

A topology changes every time someone patches a cable. Racking new hardware is rare and deliberate, so a rack elevation changes far less often. Those two facts decide which approach fits, not a feature comparison between tools.

Where generated text wins

Three properties, and they only apply when the subject changes.

It can be generated from collected state. Topology, neighbor relationships, routing adjacencies, and VLAN spans all exist in the devices already. A diagram generated from that data is accurate by construction, and rerunning the collection updates it. A hand-drawn picture has no equivalent, because it is only ever as current as the last person who edited it.

It diffs. A removed link is a removed line in a pull request. A reviewer who knows the network sees the change in the review, next to the configuration change that caused it. Two versions of a drawing require a person to spot the difference by looking.

It travels with the change. The diagram lives in the repo with the configs, so the picture moves in the same commit as the thing it depicts. Documentation stored somewhere else drifts from the first change onward, whatever anyone intends.

That covers topology, dependency maps, protocol exchanges such as a DHCP relay or an 802.1X flow, and lifecycle diagrams such as spanning tree port states.

Where a drawing tool wins

Two categories, and a drawing tool is the better tool for both.

Position on the page means something. Rack elevations, cable runs, floor plans, antenna coverage, and anything else where the drawing has to match the physical layout. A layout engine places nodes to minimize edge crossings. It will move the device you need in slot 14 next to the one it shares the most links with, because that is what it was built to do. Fighting it wastes your time and still produces a worse elevation than fifteen minutes of dragging boxes.

The diagram is drawn once for an audience. The architecture slide in a proposal, the one-pager for a steering committee, the migration overview for a customer. These need visual control a layout engine will not give you, and they are drawn once and archived, so drift is not a problem. Reaching for text here costs you an afternoon of fighting placement to produce something less persuasive.

A third category is the diagram your team will keep using. If everyone who maintains documentation is comfortable in a drawing tool and nobody is comfortable in git, a technically better approach that nobody adopts leaves you with worse documentation than you started with.

The three costs

All three are real, and worth knowing before you commit a team to this.

You give up layout control. Your levers are link length, grouping with subgraphs, and direction. That is close to all of it. Sometimes the engine produces a layout you would not have chosen, and the answer is to accept it or restructure the grouping, not to nudge a box.

Readability falls off with size. Somewhere around forty nodes a generated topology becomes a picture people stop opening. The fix is splitting, not a bigger canvas. Use one diagram per site, per tier, or per function, and link them together. This is a real design task, and generating one enormous accurate diagram is a common way to end up with an accurate diagram nobody reads.

Your teammates have to read and edit text. Reading a rendered diagram is no harder than any other picture, but editing means a text file and a pull request. On a team already working that way, the cost is close to zero. A team that keeps documentation in a shared drive is starting from a different place. Moving to text is a real change in habit, and ignoring that gets the conversion abandoned within a couple of months.

A split that works

Rather than converting by tool, sort by what the diagram answers.

The diagram answers	Approach
What connects to what, right now?	Generated text, from neighbor data.
What depends on what?	Text, maintained by hand or generated from a source of truth.
In what order do these messages happen?	Text, as a sequence diagram.
What states does this move through?	Text, as a state diagram.
What is physically where?	Drawing tool, or a generator that takes explicit coordinates.
What should the customer understand in one slide?	Drawing tool.

The first four are what a network team pulls up during an outage. The other two are what gets shown to someone outside the team.

Tools in each category

These are named without endorsement.

For text: Mermaid renders natively in GitHub, GitLab, Obsidian, and VS Code, which is why it is the low-friction starting point. Graphviz gives more layout control and less native rendering. D2 and PlantUML sit in between, with their own strengths and their own rendering requirements.

For drawing: the established diagramming applications all do rack elevations and polished deliverables well, and the differences between them are about collaboration and licensing rather than capability.

For the physical layer specifically, a source of truth built for infrastructure inventory is a better answer than either. If rack and cable data lives in a system, generating elevations from that system beats maintaining a drawing that duplicates it.

Where to start

Pick the one diagram that is currently wrong and currently painful. For most teams that is the topology, because it is the one people check during an outage and the one that drifts fastest.

Generate that one. Leave everything else where it is. If it stays accurate for a quarter with nobody maintaining it, converting the next one is an easy argument. If it does not, you learned that for the price of one diagram.

The mechanics of generating that first one are in generating a diagram from LLDP output, and keeping it honest afterward is in keeping diagrams from going stale. The network diagram generator will show you what your own network looks like in this form before you commit to anything.