When to Use Which Diagram

Masters of any craft don't just know their tools—they know when to use each tool with precision and purpose. A master chef selects knives based on the task; a master carpenter chooses tools based on the joint. Similarly, mastering software design diagrams means developing the judgment to select the right diagram for each communication goal.

The previous pages examined when to use class diagrams, sequence diagrams, and use case diagrams individually. This page synthesizes that knowledge into a unified decision framework—a mental model that guides you from 'I need to communicate something about this design' to 'This specific diagram type is optimal.'

Before diving into decision frameworks, we must establish the foundational principle: diagrams exist to communicate. They are not ends in themselves, not bureaucratic requirements, not proof of rigorous methodology. They are communication tools, and like all tools, their value depends entirely on how effectively they serve their purpose.

The Tragic Anti-Pattern

Many projects suffer from what we might call 'diagram theater'—diagrams created to satisfy process requirements rather than to communicate understanding. These diagrams are:

• Created once, never updated, immediately obsolete
• Generated mechanically from code without curation
• Too detailed to be readable, too abstract to be useful
• Stored in documentation repositories, never consulted

This is waste, and it gives UML and design diagrams a bad reputation. The antidote is the communication-first principle: every diagram must answer a specific question for a specific audience.

All design communication falls along three primary dimensions. Understanding these dimensions is the key to diagram selection:

Dimension 1: Structure vs. Behavior

This is the most fundamental distinction. Are you communicating about:

• Structure: What exists? What are the parts? How are they organized? How do they relate to each other statically? → Class diagrams, component diagrams, package diagrams

• Behavior: What happens? How do parts interact? What's the flow of control? How does state change? → Sequence diagrams, activity diagrams, state diagrams

Many design questions have a primary dimension. 'What classes do we need?' is structural. 'How do they work together to process a request?' is behavioral. The dimension guides the diagram category.

Dimension 2: Abstraction Level

At what level of abstraction are you communicating?

• Requirements Level: What the system does for users, without any implementation detail. → Use case diagrams

• Design Level: How the system is structured and how components interact, without deployment or runtime details. → Class diagrams, sequence diagrams at component level

• Implementation Level: Precise code-level details—every method, every parameter, every line. → Detailed class diagrams, implementation-level sequences

• Deployment Level: Where software runs, how it's distributed, what infrastructure supports it. → Deployment diagrams, C4 context diagrams

Matching abstraction level to audience is critical. Executives need requirements level; developers need design or implementation level; operations needs deployment level.

Dimension 3: Scope

How much of the system are you addressing?

• System Scope: The entire system and its external context. → System context diagrams, high-level use case diagrams

• Subsystem/Component Scope: A major piece of the system. → Package diagrams, component-level class diagrams

• Class/Object Scope: Individual classes and their immediate collaborators. → Detailed class diagrams, sequence diagrams

• Method Scope: The internals of a single operation. → Flowcharts, detailed sequence diagrams, activity diagrams

Scope determines how much to show. Trying to show the entire system at method-level detail produces unusable diagrams.

Now we synthesize the dimensions into a practical decision framework. This is a series of questions that lead to the optimal diagram choice.

Step 1: Identify the Primary Question

What is the main question you're trying to answer? State it explicitly. Examples:

• 'What user roles interact with the system and what can they do?'
• 'How are the domain entities structured and related?'
• 'What happens when a user places an order?'
• 'What are the valid states of an order and how do they transition?'

Step 2: Determine the Dimension

Based on the question, identify the primary dimension:

• Questions about what exists, what contains what, how things relate → Structure
• Questions about what happens, in what order, how things flow → Behavior
• Questions about what users can do, what's in scope → Requirements

Step 3: Match to Diagram Type

With the primary dimension identified, select the diagram:

For Structure Questions:

• 'What types/classes exist and how do they relate?' → Class Diagram
• 'How are classes organized into packages/modules?' → Package Diagram
• 'What major components exist and how do they depend?' → Component Diagram

For Behavior Questions:

• 'How do objects collaborate to accomplish X?' → Sequence Diagram
• 'What's the workflow/process for doing X?' → Activity Diagram
• 'What states does object Y go through?' → State Diagram

For Requirements Questions:

• 'What can users do with this system?' → Use Case Diagram
• 'What are the major capabilities?' → Use Case Diagram (summary level)

Step 4: Adjust for Audience and Purpose

The basic diagram type is now selected. Adjust the detail level:

• For non-technical stakeholders: Higher abstraction, less notation detail, more labeling
• For architects: Design-level abstraction, key relationships, architectural patterns
• For implementing developers: More detail, accurate signatures, implementation guidance
• For debugging/analysis: Maximum detail, possibly generated from code

Step 5: Constrain the Scope

Decide what's in the frame and what's out. A good diagram shows:

• Enough context to understand the subject
• Enough detail to answer the question
• No more than can be grasped in a few minutes of study

If you need to show more, create multiple diagrams with clear relationships between them.

The following table provides a quick reference for common design communication needs and the appropriate diagram choices. Use this as a rapid lookup when starting any diagramming task.

Reading the Table:

The 'Primary Diagram' column shows the diagram type that most directly answers the question. The 'Supporting Diagrams' column shows additional diagrams that provide helpful context.

Note that many questions benefit from a combination. Showing class structure without behavior, or behavior without structure, often leaves the audience with incomplete understanding. The primary/supporting pattern helps balance completeness with focus.

Real design communication often requires multiple diagrams working together. Here are common scenarios and effective diagram combinations:

Scenario 1: New Feature Design

You're designing a new feature from scratch. Stakeholders need to validate requirements; architects need to review the design; developers need implementation guidance.

• Use Case Diagram: Shows what users can do with the feature (for stakeholders)
• Class Diagram: Shows the new classes and their relationships (for architects and developers)
• Sequence Diagram: Shows how the main scenario is realized (for developers)

This trio—use case, class, sequence—is the standard set for feature design documentation.

Scenario 4: Design Pattern Application

You're applying a design pattern (Strategy, Observer, Factory, etc.) and want to explain how it works in your context.

• Class Diagram: Shows the pattern's structural elements in your domain
• Sequence Diagram: Shows how the pattern behaves at runtime

Design pattern explanations almost always use both structure and behavior diagrams—the pattern is defined by both its class relationships and its interaction patterns.

Scenario 5: Architecture Overview

You need to explain the overall system architecture to new team members or stakeholders.

• Use Case Diagram (summary level): Shows major system capabilities
• Component Diagram: Shows major building blocks and their relationships
• Class Diagrams (per component): Show internal structure of each component

This layered approach—overview first, then drill-down—helps audiences build understanding progressively.

Understanding what to avoid is as valuable as knowing what to do. Here are common anti-patterns in diagram selection:

Anti-Pattern 1: The Everything Diagram

Symptoms: A single massive diagram with 100+ elements trying to show structure AND behavior AND deployment.

Why it fails: Cognitive overload. Readers can't extract any useful information because everything competes for attention.

Solution: Split into multiple focused diagrams, each answering one question.

Anti-Pattern 2: The Wrong Audience Diagram

Symptoms: Showing a detailed class diagram with private methods and implementation types to business stakeholders.

Why it fails: The diagram uses vocabulary and notation the audience doesn't understand.

Solution: Match abstraction level to audience. Use case diagrams for business, class diagrams for developers.

Anti-Pattern 3: The Out-of-Date Diagram

Symptoms: Diagrams that were accurate six months ago but haven't been updated as the code evolved.

Why it fails: Out-of-date documentation is worse than no documentation—it actively misleads.

Solution: Either commit to maintaining diagrams (include in definition of done), or explicitly mark diagrams with their vintage and treat as historical context.

Anti-Pattern 4: The Diagram Avoidance

Symptoms: Describing complex multi-party interactions in paragraphs of text when a sequence diagram would communicate instantly.

Why it fails: Forces readers to build the visual model in their heads; different readers construct different models; leads to misunderstandings.

Solution: Recognize when visual is better than textual. If you're describing spatial or temporal relationships, draw them.

The decision framework provides explicit guidance, but experienced designers develop intuition that makes the choice feel automatic. Here's how to develop that intuition:

Practice Active Selection

Every time you need to communicate about design, consciously go through the framework:

1. What's my question?
2. Structure, behavior, or requirements?
3. What's the right abstraction level?
4. Who's my audience?

After you've done this consciously a hundred times, it becomes automatic.

Learn from Examples

Study well-designed systems and their documentation. Look for:

• What diagrams did they choose to include?
• At what level of detail?
• How do the diagrams relate to each other?

Good examples include framework documentation, architecture decision records, and design pattern catalogs.

Seek Feedback

After presenting diagrams, ask:

• Did this answer your question?
• Was anything unclear?
• Did you need information that wasn't shown?

Feedback reveals mismatches between your diagram choice and the audience's needs.

Develop a Personal Toolkit

Over time, build your own library of diagram templates and patterns. When you create a diagram that works particularly well for a certain type of question, save it as a reference. Build a personal collection of 'this diagram for this situation.'

We've completed the module on selecting the right diagram for every design situation. Let's consolidate the key insights:

Module Complete:

You've now completed the module on choosing the right diagram for any design situation. You understand:

• When to use class diagrams for structural representation
• When to use sequence diagrams for behavioral interactions
• When to use use case diagrams for requirements capture
• How to match any design question to the optimal diagram type

This knowledge is foundational for all design documentation and communication. As you continue through the curriculum, you'll apply these principles to increasingly complex designs, but the core question will always be the same: What am I trying to communicate, and which diagram communicates it best?