Which diagram type to use for each purpose
| Diagram type | Use when | Don't use when |
|---|---|---|
| Flowchart | Showing a decision process or algorithm with branching paths | Showing system components — use architecture diagram instead |
| Sequence diagram | Showing the order of messages/calls between components over time | Showing static structure — use class or ER diagram |
| ER diagram | Showing database tables and their relationships (foreign keys) | Showing API flows — use sequence diagram |
| Architecture diagram | Showing how systems, services, and infrastructure connect | Showing code-level class relationships — use class diagram |
| Class diagram | Showing OOP classes, interfaces, and inheritance | Showing runtime message flow — use sequence diagram |
| State diagram | Showing how an object transitions between states | Showing multi-component interactions — use sequence diagram |
The diagram mistake that adds confusion instead of clarity
The most common diagram mistake: putting too much in one diagram. A single diagram that shows database schema, API endpoints, UI components, and infrastructure all at once is unreadable — every reader sees different things and leaves with different mental models. The rule of thumb: one diagram, one audience, one question. An architecture diagram for a new engineer answers "how do the systems connect?". A sequence diagram for a code reviewer answers "what happens during checkout?". They are different diagrams for different questions.
Diagrams generated from text (Mermaid, PlantUML, Graphviz) age better than hand-drawn diagrams — they live next to the code in version control and update when the description updates. A PNG exported from a drawing tool and attached to a Confluence page will be out of date within three months.