Exercises — Chapter 32: Visual Storytelling

Writing and diagramming are learned by doing. Every task here asks you to produce, revise, or critique a real diagram—not to pick a letter. Draw in Mermaid where you can (so you practice the book's format), or sketch on paper and describe it. For each diagram you make, write the one-sentence caption and the alt-text too: that's where the communication actually happens.

Difficulty: ⭐ foundational · ⭐⭐ intermediate · ⭐⭐⭐ challenging · ⭐⭐⭐⭐ extension. Selected solutions and rubrics: appendices/answers-to-selected.md. Open-ended tasks get a self-assessment rubric here.

Part A — Analyze This ⭐

Diagnose what works and what's broken. Name the specific rule from the chapter, not just "it's confusing."

A1. A design doc contains a diagram with eight boxes labeled App, Service, Service2, Cache, DB, Queue, Worker, Thing, connected by twelve unlabeled arrows, four of which cross. List the three specific problems and the chapter section that addresses each.

A2. A README shows an ER diagram of all 38 tables in the database, every column listed, no relationship verbs. What task is a README reader doing, and why is this the wrong diagram for it? What would you show instead?

A3. An architecture diagram for a leadership pitch shows Client → API → Database—three clean boxes. The real system has a cache, a message queue, two third-party integrations, and a read replica. Is the diagram wrong? Explain the difference between "simplified" and "misleading," and name the one fix that would make this diagram honest.

A4. A sequence diagram of a login flow uses solid arrows for every message, including the responses. What does the reader lose? What's the convention the diagram broke?

A5. A flowchart has a diamond (decision) with two arrows leaving it, both unlabeled, and one arrow that leaves the chart and points to nothing. Name the two rules violated.

A6. Someone draws a five-box flowchart to document: "Merge to main → CI runs → deploy to staging → smoke test → deploy to production." There are no decisions. Is a flowchart the right call? What would you use, and why?

A7. Two diagrams in the same doc use a dashed line. In the first it means "asynchronous event"; in the second it means "planned, not yet built." There is no legend in either. What's the problem, and what two things fix it?

A8. An architecture diagram mixes a load balancer, a UserService class, a Postgres instance, and a box labeled "the checkout process." A new engineer says "I can't tell what kind of thing each box is." Name the failure and the discipline (and its source) that prevents it.

Part B — Revise This ⭐⭐

Each task gives you a weak diagram (described or in Mermaid) and a goal. Produce the improved version—the diagram plus its caption and alt-text. Don't just describe the fix; make it.

B1. Name the boxes and arrows. Here is a bare diagram:

flowchart LR
    A --> B
    B --> C
    B --> D
    C --> E

The author tells you: A is the web frontend, B is the order API, C is the orders database, D is an event queue, E is a notification worker that reads the queue (so the arrow is actually D→E, not C→E—there's a bug). Redraw it with real names, labeled arrows (what each carries), the corrected edge, and one consistent direction. Write the caption and alt-text.

B2. Pick a level. An architecture diagram crams a context-level relationship (the system talks to a payments provider), a container-level piece (a React web app), and a code-level detail (a PaymentValidator class) into one picture. Split it into the two diagrams the chapter recommends, and say which C4 level each is.

B3. Add cardinality. This ER-style sketch shows three entities connected by plain lines with no cardinality and no verbs: AUTHOR —— BOOK —— PUBLISHER. The real model: an author can write many books; a book has exactly one publisher; a publisher publishes many books. Redraw it as a proper ER diagram with crow's-foot cardinality and relationship verbs.

B4. Make the omission honest. A diagram captioned "Figure 4: System Architecture" shows only the happy path and hides all retry/failure handling, which the system genuinely has. Without redrawing the diagram, write (a) an honest caption that scopes it correctly and (b) one sentence describing the second diagram you'd add and what type it would be.

B5. Turn prose into the right diagram. Convert this paragraph into whichever diagram type fits, and justify the type in one sentence: "When a user submits a payment, the checkout service first reserves inventory, then charges the card via the payment provider; if the charge succeeds it confirms the order and emails a receipt, but if the charge fails it releases the inventory reservation and shows an error."

B6. Untangle the spaghetti. You're given the §32.8 / Productive-Struggle diagram: eight boxes (Frontend, Backend, Service, Service2, Cache, DB, Queue, Worker), fourteen unlabeled arrows, several crossing. Apply the chapter's three-step fix in order. Show your result as a clean Mermaid diagram for one idea (request flow OR deploy topology—pick one and say which).

B7. Right-size the detail. An exec asked Raj for "a diagram of the whole platform." He's tempted to send the container diagram with all five services and every arrow. What should he send instead, and why? Produce the diagram you'd actually send to the exec.

Part C — Choose the Right Diagram Type for These Scenarios ⭐⭐–⭐⭐⭐

For each scenario, (1) name the single best diagram type, (2) justify it in one sentence by the reader's task, and (3) draw a small version in Mermaid with a caption. If you think the honest answer is "no diagram—use prose or a table," say so and explain.

C1. A new backend engineer needs to understand how an order event fans out to a notification service and an analytics service the day they join.

C2. An on-call runbook must tell a stressed engineer what to do when the nightly batch job fails, depending on whether it's a data error, a timeout, or an out-of-disk error.

C3. A security reviewer asks: "Which of our services are internet-facing, and what's behind the firewall?"

C4. A junior developer can't figure out the order of calls in your token-refresh flow and keeps getting a 401.

C5. A teammate needs to understand that a User can have many Subscriptions, each Subscription belongs to exactly one Plan, and a Plan can back many subscriptions.

C6. A product manager asks, "What are the four big pieces of our system and roughly how do they fit together?"—they will not read past one picture.

C7. You need to document that an order moves through pending → paid → shipped → delivered, and can jump to cancelled from any of the first three.

C8. A stakeholder asks for "the exact p95 latency and error rate of each of our six services this quarter."

Part D — Synthesis and Critical Thinking ⭐⭐⭐

D1. The misleading-diagram audit. Find a real architecture diagram (your own project, an open-source README, a public blog post). Identify one thing it implicitly claims is "simple" or "safe" that you suspect isn't (a hidden cache, an un-shown failure mode, a glossed-over integration). Write a short paragraph: what does the diagram imply, what does it hide, and what would make it honest? Connect your answer to the chapter's claim that a clean diagram is persuasive even when wrong, and to the Challenger lesson from Chapter 9.

D2. Cross-chapter integration (Ch 9 + Ch 30 + this chapter). Chapter 9 said a figure needs a caption that interprets; Chapter 30 said a slide's title should be the assertion and the body the evidence. Write one paragraph arguing that these are the same principle applied to three media (chart, slide, diagram), and state the single sentence that captures all three.

D3. Translate one structure for three audiences. Take a system you know. Produce three artifacts: (a) a context diagram for an executive, (b) a container diagram for the implementing team, (c) a one-paragraph prose description for a release-notes audience who won't look at a diagram at all. For each, write one sentence on why that representation fits that audience (theme: audience is everything).

D4. The "is a diagram even needed?" test. Find a doc you've written (or a section of your portfolio piece) that currently has a diagram. Argue for or against keeping it using the §32.1 test. If you'd cut it, say what prose replaces it; if you'd keep it, name the shape the reader needs that words can't carry.

D5. Diagrams-as-code vs. drawing tools. Your team is split: half want Mermaid in the repo, half want polished Lucidchart diagrams. Write the three-sentence recommendation you'd post, naming the trade-off (sync vs. polish/layout) and the deciding question. Note where the chapter's "keep the source" rule lands for each.

Part M — Mixed Practice (Interleaved) ⭐⭐–⭐⭐⭐

These mix this chapter with earlier ones, so you must first decide which tool/principle applies.

M1. (Ch 32 + Ch 22 Instructions) A teammate documents a 9-step deployment as a flowchart with no decisions in it. Should this be a flowchart, a numbered procedure (Chapter 22), or a sequence diagram? Decide, justify, and produce the better artifact.

M2. (Ch 32 + Ch 25 README) You're improving Raj's README (the makeover from Chapter 25). It currently has zero diagrams and a wall of prose describing the system's parts. Decide whether to add a diagram, which type, and at which level—then draw it and write its caption. Defend why it belongs in a README specifically.

M3. (Ch 32 + Ch 10 Design) A diagram is correct but uses red and green to distinguish "synchronous" from "asynchronous" edges, with no other cue. Name the Chapter 10 accessibility rule it breaks, and fix it (two changes).

M4. (Ch 32 + Ch 9 Captions) Here is a diagram caption: "Figure 7: Architecture." Rewrite it to Level 3 (interpretation) for a container diagram of a checkout system, so a caption-only reader leaves with the one idea.

M5. (Ch 32 + Ch 12 Editing) Apply the editing hierarchy (Chapter 12) to a diagram instead of prose. In what order should you fix an overcrowded diagram—rename boxes, pick the level, label arrows, prettify layout? Write the order and one sentence on why "prettify layout" is last.

M6. (Ch 32 + Ch 27 Data) A data memo (Chapter 27) includes a flowchart of the analysis pipeline (extract → clean → model → report) with one branch: "if data quality check fails, stop and flag." Is a flowchart right here, or is this a case for prose? Decide and justify.

Part E — Extension ⭐⭐⭐⭐

For motivated readers and the Deep Dive track.

E1. Build the C4 set. For a system you know well, produce a real two-diagram C4 set in Mermaid: a Context diagram and a Container diagram. Then write a 150-word note on what you deliberately left out of each level and why leaving it out made the diagram communicate better.

E2. The honest second view. Take any clean "happy-path" architecture diagram and add the failure-mode view the chapter recommends: a sequence diagram showing what happens when one dependency (a payment provider, a cache, a downstream API) times out or errors. Caption both so a reader knows which question each answers.

E3. Diagram a protocol you don't fully understand—to understand it. Pick a protocol or flow you find fuzzy (OAuth refresh, a database transaction with rollback, a CI/CD pipeline). Draw the sequence diagram. Write two sentences on what the act of diagramming forced you to pin down that prose let you stay vague about—an instance of the book's thesis that diagramming, like writing, is thinking (Chapter 1).

Self-Assessment Rubric (for open-ended diagram tasks)

Rate each diagram you produced:

Aim for 3s. Any 1 is a rewrite, not a polish—fix meaning before appearance.