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:

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.

Advertisement

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:

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:

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:

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:

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

QuestionDiagram 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.