Diagrams in Documentation: When to Draw One, and What to Draw It With

Draw a diagram when the thing you are describing is fundamentally a shape: an order of events, a set of states and the transitions between them, a topology, a branching decision. Those are genuinely hard to hold in prose and trivial to read as a picture. Everything else (a list of features, a set of steps, a comparison) is faster to read as text, and a diagram of it is decoration that somebody now has to keep accurate.

And when you do draw one, write it as text that lives in the repository beside the page. A PNG in a shared drive is a diagram that will be wrong within two releases and that nobody can correct.

When does a diagram earn its place?

The last two rows are where most diagram effort goes and where it returns least. A box-and-arrow rendering of a bulleted list is slower to read than the list, impossible to search, and now needs updating whenever the list does.

Diagrams as code, not as images

Write diagrams in a text format that renders at build or view time. The advantages are not aesthetic; they are maintenance advantages, and they compound.

• It diffs. A reviewer can see that an arrow was reversed. Nobody can review a changed PNG.
• It lives with the page. The diagram and the prose it explains change in the same commit, so they cannot drift apart quietly.
• Anyone can fix it. Correcting a diagram does not require the original file, the original tool, or the person who made it.
• It follows the theme. A rendered diagram can take its colours from the page, so it does not sit on a white rectangle in dark mode.
• It is searchable. The node labels are text, both to your own search index and to anything else reading the page.

Mermaid is the pragmatic default: it is plain text, it covers the four diagram types worth drawing, and it renders in most documentation toolchains. Here is a request-handling flow written out as source:

flowchart LR
    A[Request] --> B{Authenticated?}
    B -- no --> C[401 Unauthorized]
    B -- yes --> D{Under rate limit?}
    D -- no --> E[429 Too Many Requests]
    D -- yes --> F[Handler]

And here is the same source, rendered:

flowchart LR
    A[Request] --> B{Authenticated?}
    B -- no --> C[401 Unauthorized]
    B -- yes --> D{Under rate limit?}
    D -- no --> E[429 Too Many Requests]
    D -- yes --> F[Handler]

A sequence diagram is the other type that consistently pays for itself, because the alternative is asking the reader to hold five ordered interactions in their head while reading a paragraph about them:

sequenceDiagram
    participant C as Client
    participant A as Auth service
    participant D as Docs API
    C->>A: POST /token (client credentials)
    A-->>C: access_token (expires in 3600s)
    C->>D: GET /v1/documents (Bearer token)
    D->>A: introspect token
    A-->>D: valid, scope=read
    D-->>C: 200 OK, documents

Rules for a diagram somebody can actually read

1. One idea per diagram. If it needs a legend with more than three entries, it is two diagrams.
2. Under about a dozen nodes. Past that, readers stop tracing edges and start skimming, which is the same as not reading it.
3. Label the edges, not just the boxes. “Client → Auth” says nothing. “Client → Auth: exchange credentials for a token” says everything.
4. Left-to-right or top-to-bottom, consistently. Mixed direction inside one document costs the reader a moment of reorientation on every diagram.
5. Match the vocabulary in the prose exactly. If the diagram says “Docs API” and the paragraph says “the documents service”, the reader has to work out that these are the same thing.
6. No colour-only meaning. If red means failure, the failing node must also say so in words.

Accessibility is not optional here

A diagram is invisible to a screen-reader user and to anyone whose rendering failed. Both groups need the information, and neither is served by alt="architecture diagram".

This is also the accessibility rule most often missed on documentation sites, alongside colour contrast, and both are covered in A WCAG 2.1 AA Checklist for Documentation Sites.

What not to diagram

Three diagrams appear in almost every documentation site and almost never help.

• The whole architecture, on one page. Forty boxes, unreadable at any zoom level, out of date the week it was made. Draw the three components a reader needs for the page they are on.
• The org chart of your product’s concepts. A hierarchy diagram of your object model is a nested list drawn slowly.
• The generic “how it works” overview. If nobody can say which question it answers, it is answering none of them.

A diagram nobody maintains is not documentation. It is an artefact of the day it was drawn, presented with the authority of a fact.

Common questions