Diagrams communicate complex systems more effectively than paragraphs of text. But choosing the wrong diagram type for the job can confuse instead of clarify. Here's a practical guide to the most common diagram types and when to use each one.
Flowcharts
Flowcharts show the sequential steps in a process. They use standardised shapes — rectangles for actions, diamonds for decisions, ovals for start/end points. Use flowcharts when you need to:
- Document a business process or approval workflow
- Map out the logic of a function or algorithm
- Show the decision points in a user journey
- Onboard new team members to a process
Keep flowcharts simple. If a flowchart has more than 20-30 nodes, it's probably trying to document too much at once. Break it into sub-processes or use a swimlane diagram to show responsibilities.
Sequence Diagrams
Sequence diagrams show interactions between objects or systems over time. They're read top-to-bottom, with time flowing downward and messages passing horizontally between participants. Use them for:
- API request/response flows (client → server → database → response)
- Authentication and authorisation flows (OAuth, SAML)
- Microservice communication patterns
- Protocol-level interactions (TCP handshake, TLS negotiation)
Sequence diagrams are particularly powerful for showing asynchronous behaviour and timeouts, which flowcharts struggle to represent.
Entity-Relationship (ER) Diagrams
ER diagrams show the structure of a database — tables, columns, relationships between tables, and cardinality (one-to-one, one-to-many, many-to-many). Use them when:
- Designing a new database schema
- Documenting an existing database for new team members
- Communicating schema changes to stakeholders
- Planning data migrations
Include cardinality notation (crow's foot or Chen notation) to make relationships explicit. A diagram showing tables without their relationships is just a list, not a diagram.
Class Diagrams
Class diagrams show the static structure of an object-oriented system — classes, attributes, methods, and relationships (inheritance, composition, association). Use them for:
- Designing the architecture of an OOP codebase before implementation
- Documenting existing code structure for new developers
- Planning refactoring of a large codebase
- Teaching OOP concepts
State Diagrams
State diagrams (or state machine diagrams) show the states an object can be in and the transitions between those states. Use them for:
- UI component states (idle, loading, error, success)
- Order or payment processing (pending, paid, shipped, delivered, returned)
- Game state management (menu, playing, paused, game-over)
- Protocol or communication state machines
State diagrams are invaluable for finding edge cases. When you draw out every state and transition, missing states and impossible transitions become obvious.
Choosing the Right Diagram
| Question | Diagram Type |
|---|---|
| What steps happen in this process? | Flowchart |
| How do these systems interact over time? | Sequence |
| What's the database structure? | ER Diagram |
| How are these classes related? | Class Diagram |
| What states can this object be in? | State Diagram |
Text-Based vs Visual Diagrams
Tools like Mermaid.js and PlantUML let you write diagrams as text, which is version-controllable and integrates with documentation. The diagram tool on this site supports both Mermaid and Nomnoml syntax. Write your diagram as text, and it renders instantly — no drawing skills required.
Text-based diagrams have a major advantage in documentation: they live alongside your code in the same repository, update with the same pull requests, and show diffs in code review. Visual diagrams in separate files (PNG, SVG) tend to drift out of sync with the code they document.