flowchart7 min read

Flowchart best practices

Direction, density, and the secret of when to switch from TD to LR.

TL;DR

If your diagram has a clear direction of time, reach for a sequence. If it has decision points, use a flowchart. If you find yourself drawing both, your diagram is doing too much — split it.

Why this matters

The single biggest mistake we see in code review is teams reaching for whichever diagram type they remember the syntax for. The result is a flowchart pretending to be a sequence diagram, or vice versa, and the reader spends 30 seconds decoding the metaphor before they even read the content.

The right diagram type makes the rest of the work easier. The wrong one makes everything harder.

A worked example

Suppose you're documenting an OAuth2 authorization-code flow. Each step is a message between actors, and the order is critical:

oauth.mmd

sequenceDiagram
    autonumber
    participant U as User
    participant W as Web app
    participant A as API
    participant D as Database
    U->>W: Click class="code-str">"Save"
    W->>A: POST /diagrams
    A->>D: INSERT INTO diagrams
    D-->>A: id = 4f2…
    A-->>W: 201 Created
    W-->>U: ✓ Saved

Now compare with the equivalent in a flowchart — same information, much harder to read because the time axis is gone:

Three rules of thumb

Direction of time matters? Sequence diagram.
Branching with decisions? Flowchart.
Hierarchical relationships? Class or ER diagram.

Next steps

Up next

C4 architecture in three diagrams