The Following Figure Shows An Example Of

You're reading a technical paper, documentation, or textbook. Which means you hit a figure. Right below it, in italics: The following figure shows an example of...

And you pause. 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.

Basically one of those small, invisible problems that compounds. That said, a poorly captioned figure wastes the reader's time. Day to day, a well-captioned one teaches. 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. But "Figure 3: System Architecture. " Done. Move on.

But a caption is not a label. 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. Still, reviewers check figures for correctness. Because of that, skimmers scan figures first. Future-you comes back six months later and only looks at the diagrams.

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.

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.

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.

The reader builds a mental model by stitching figures together. Weak captions force them to read the surrounding prose just to understand the picture*. On top of that, 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. 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.

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. It's a specific variant. That said, 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. In practice, 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. Day to day, the figure shows the shape*. The caption gives the scale*.

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.

Common Mistakes / What Most People Get Wrong

The "Figure 1 Shows..." Crutch

"The following figure shows an example of a cache miss."

If you found this helpful, you might also enjoy an animal that the predator feeds upon or symptoms of excessive stress include all of the following except:.

We know. It's a figure. We're looking at it. The word "shows" wastes the first five words of the caption — the most valuable real estate.

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. That's why they don't need you to narrate the act of looking. least-connections? Which means weighted? Consider this: tell them what the even distribution means* for capacity planning, or what "even" actually means in this context (round-robin? ).

Inconsistent Granularity

Figure 2: "System overview"

Figure 3: "Detailed sequence of the validateToken RPC call including retry backoff intervals"

One is a continent. The reader gets whiplash. The other is a driveway. Pick a zoom level per section, or explicitly signal the zoom change: "Zoomed-in view of the token validation step from Figure 2.

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? Figure 5 shows the separation: session cache (TTL 24h) vs. rate-limit counters (TTL 1m).

Now the figure has a purpose. Because of that, it's not "the Redis diagram. " It's "the answer to why there are two connections.

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.

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.

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.

Label:

• The component that answers the question.
• The component whose behavior changes (e.Because of that, g. , “cache miss → DB fallback”).
• The component that’s surprising or non-obvious.

Don’t label:

• Standard infrastructure (unless it’s the point). Plus, - 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-service token 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.

The difference between a useful figure and a useless one isn’t complexity. It’s clarity of intent. 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.