You're reading a technical paper, documentation, or textbook. You hit a figure. Right below it, in italics: The following figure shows an example of...
And you pause. Day to day, because the caption tells you that* it's an example. But it doesn't always tell you why it matters, what* to look for, or how to read it It's one of those things that adds up. Worth knowing..
This is one of those small, invisible problems that compounds. A well-captioned one teaches. Consider this: a poorly captioned figure wastes the reader's time. The difference isn't talent — it's a handful of habits anyone can learn.
What Is a Figure Caption Really For
Most people treat captions as labels. "Figure 3: System Architecture." Done. Move on.
But a caption is not a label. Practically speaking, it's the bridge between the visual and the verbal. The figure shows what*. The caption tells so what*.
In technical communication, the figure-caption pair is often the most-read part of the entire document. Skimmers scan figures first. Reviewers check figures for correctness. Future-you comes back six months later and only looks at the diagrams Easy to understand, harder to ignore..
If the caption says only "Example of a state machine," the reader has to reverse-engineer the point. If it says "State machine for the order fulfillment flow, showing how the pending_payment state transitions to shipped only after payment_confirmed fires," the reader gets it* instantly It's one of those things that adds up..
The Three Jobs Every Caption Must Do
Identify — what am I looking at? (Type, scope, context)
Orient — where does this fit? (System, process, timeline, comparison)
Direct — what should I notice? (The key insight, the anomaly, the pattern)
Miss any of these, and the figure becomes decoration. Not communication The details matter here..
Why It Matters / Why People Care
You've seen the bad version. A 40-page spec with 12 diagrams. Every caption: "Architecture diagram." "Sequence diagram." "Class diagram Not complicated — just consistent..
The reader builds a mental model by stitching figures together. Weak captions force them to read the surrounding prose just to understand the picture*. That's backwards. The picture should reduce the reading load, not increase it.
Strong captions change the economics of reading:
- Reviewers catch errors faster because the expected behavior is stated in the caption
- Onboarding engineers grasp system boundaries without reading three chapters
- Future maintainers (including you) recover context in seconds, not minutes
- Non-technical stakeholders actually understand what they're approving
There's also a writing discipline effect. So when you have* to write a caption that directs attention, you often realize the figure itself is cluttered, ambiguous, or showing the wrong thing. The caption is a design review tool Not complicated — just consistent..
How It Works: Writing Captions That Teach
Start With the Figure Type — But Don't Stop There
"Sequence diagram" is a type. "Sequence diagram showing the retry logic for idempotent POST requests" is a caption.
The type helps the reader choose the right mental parser. The specific subject tells them which* sequence, which* logic, which* concern.
Name the Scenario, Not Just the Component
Bad: "User authentication flow"
Better: "User authentication flow for passwordless login via magic link, including the 15-minute token expiry edge case"
The second one tells the reader: this isn't the general* auth flow. Still, it's a specific variant. With a specific constraint. That specificity is the difference between "I know this" and "I need to read this.
Highlight the Non-Obvious
If the figure shows a happy path, the caption should say so — and ideally point to where the unhappy paths live.
Figure 4: Happy-path checkout flow. Error handling for inventory reservation failures shown in Figure 5.*
Now the reader knows: this is incomplete by design. They're not missing something. They know where to look next.
Use the Caption to Define Notation — Once
If your diagrams use custom shapes, line styles, or color coding, define it in the first* figure's caption. Reference it in later ones.
Figure 1: Service dependency graph. Solid lines = synchronous RPC. Dashed lines = async messaging. Red = external dependencies.
Figure 3: Order service dependencies. Dashed line to Payment indicates async event publishing.*
The second caption doesn't re-explain. It trusts the reader — but only because the first one did the work.
Quantify When It Matters
"High latency" is vague. "P99 latency > 2s" is useful.
If the figure shows a performance characteristic, the caption should include the numbers that make the insight concrete. The figure shows the shape*. The caption gives the scale* Still holds up..
Reference the Source of Truth
If the figure was generated from code, say so. If it's manually drawn and might drift, say that too.
Generated from docs/architecture/dsl/service_graph.dsl — update there, then regenerate.*
Manually maintained — may not reflect recent auth-service changes.*
This one line saves hours of "wait, is this diagram current?" investigations Practical, not theoretical..
Common Mistakes / What Most People Get Wrong
The "Figure 1 Shows..." Crutch
"The following figure shows an example of a cache miss."
We know. Even so, it's a figure. Even so, we're looking at it. The word "shows" wastes the first five words of the caption — the most valuable real estate Easy to understand, harder to ignore..
Cut it. Start with the subject: "Cache miss scenario: cold start with empty Redis cluster, triggering DB fallback."
Captions That Repeat the Prose
Paragraph above: "The system uses a circuit breaker to prevent cascade failures."
Caption: "Circuit breaker preventing cascade failures."
If the caption adds nothing the prose didn't already say, delete the caption or rewrite the prose. One of them is redundant.
The "As You Can See" Trap
"As shown in the figure, the load balancer distributes requests evenly."
The reader is looking at the figure. least-connections? They don't need you to narrate the act of looking. Tell them what the even distribution means* for capacity planning, or what "even" actually means in this context (round-robin? weighted?).
Inconsistent Granularity
Figure 2: "System overview"
Figure 3: "Detailed sequence of the validateToken RPC call including retry backoff intervals"
One is a continent. In real terms, the other is a driveway. On top of that, the reader gets whiplash. Pick a zoom level per section, or explicitly signal the zoom change: "Zoomed-in view of the token validation step from Figure 2 That's the whole idea..
Missing the "Why This Figure Exists"
Every figure should answer a question the reader has at that moment*. The caption should make that question explicit.
Why does the API gateway have two Redis connections? On the flip side, figure 5 shows the separation: session cache (TTL 24h) vs. rate-limit counters (TTL 1m).
Now the figure has a purpose. Still, it's not "the Redis diagram. " It's "the answer to why there are two connections The details matter here..
Practical Tips / What Actually Works
Write the Caption Before the Figure
Sounds backwards. But if you can't write the caption — the point* of the figure — you don't know what the figure should show. You'll draw a kitchen sink That's the part that actually makes a difference..
Write the one-sentence caption first. *
Start With the Reader's Question, Not the Diagram
Before opening your diagramming tool, ask: What does the reader need to understand right now?* If you can’t answer that, the figure doesn’t belong in this section.
This forces you to think about purpose* before content*. It also prevents the classic “dump everything we know about this subsystem” diagram that tries to explain every edge case, internal field, and legacy component — none of which the reader cares about yet Easy to understand, harder to ignore..
Use Visual Hierarchy to Guide the Eye
A good figure doesn’t require a tour guide. Use:
- Contrast: Make the key element stand out (color, size, border).
- Grouping: Visually cluster related components so the reader sees “one thing” instead of “twelve things.”
- Direction: Arrows, numbering, or layout flow should suggest the order of reading or data movement.
If the reader’s eye lands on the wrong element first, the figure is failing — regardless of how technically accurate it is.
Label What Matters — and Only What Matters
Every label is a commitment. If you label every box, the reader treats them all as equal. If you label only the critical few, the labels become signposts Which is the point..
Label:
- The component that answers the question. That's why - The component whose behavior changes (e. Consider this: g. And , “cache miss → DB fallback”). - The component that’s surprising or non-obvious.
Don’t label:
- Standard infrastructure (unless it’s the point). Even so, - Internal fields or configuration values. - Things the reader doesn’t need to remember after reading this section.
Signal Zoom Levels Explicitly
When switching from overview to detail, don’t just drop a new figure and hope the reader connects the dots.
“Figure 4 showed the high-level flow. Figure 5 zooms in on the
auth-servicetoken validation step, highlighting the retry logic and timeout boundaries.”
This isn’t hand-holding — it’s cognitive scaffolding. The reader needs to know where they are in the system’s mental map.
Keep Figures Self-Contained
A figure should make sense even if the reader skips the paragraph above it. That means:
- The caption explains the why, not just the what*.
- Labels are clear enough to stand alone.
- No references to “the previous section” or “as mentioned above.”
If the reader has to flip back to understand what they’re looking at, the figure isn’t doing its job.
Conclusion
Figures aren’t decoration. They’re cognitive shortcuts — when done right, they let the reader skip paragraphs of explanation and land directly on understanding. When done wrong, they become obstacles that force the reader to stop, re-read, and guess what the author intended.
And yeah — that's actually more nuanced than it sounds.
The difference between a useful figure and a useless one isn’t complexity. But it’s clarity of intent. Because of that, every figure should exist to answer one question, at one level of detail, for one reason. If it can’t do that, it doesn’t belong.
And if it does? The caption should say so — before the reader ever looks at it And that's really what it comes down to..
