Chapter 2 — Make Hard Things Legible

The metaphor that shipped to production

Composite. Built from recurring patterns; no identifying detail.

The talk lands well. To explain the new event-driven platform, the speaker uses a post office: services drop letters in a box, the post office delivers them, nobody waits at the counter. The room relaxes. Someone in the third row writes post office in their notes and nothing else, because the comparison did its job — it made an unfamiliar system feel like a familiar one.

Five weeks later that engineer’s team ships a billing integration on the platform. They assume, reasonably, that a letter arrives once and arrives in the order it was posted. The platform guarantees neither. Under retry, a subset of customers gets charged twice; under partial delivery, two services hold contradictory views of the same account for eleven minutes. The postmortem calls it a misunderstanding of delivery semantics. That is accurate and useless. The engineer understood the metaphor perfectly. The metaphor was the problem: it mapped cleanly onto asynchrony and silently onto exactly-once delivery, ordering, and ownership, and nothing in the talk marked where the map stopped being true.

Analogy was never the mistake. The talk shipped a mental model into production without telling anyone which parts of it were load-bearing, and the question this chapter answers is how to explain a complex system so that the model a developer walks away with is accurate enough to predict what happens next.

Simple is not the same as shallow

Legibility is a property of an explanation: the reader can see the important parts, how they relate, what state changes and when, and which tradeoffs they have just accepted. A legible explanation of a queue tells you that messages persist, that a consumer can see the same message twice, and that you now own deduplication. A shallow one tells you it’s like a post office.

The instinct behind bad simplification is decent — remove what will confuse people. The failure is in what gets removed. Complexity that a reader can safely ignore for now should be deferred. Complexity that changes what they will build, deploy, or be paged for has to appear before the decision does, even if it makes the explanation less charming. Sequencing is the craft. You are deciding what a person needs at minute one, minute five, and month three, and building a path between those points rather than compressing all three into a paragraph.

Precision and jargon are separable, which is where a lot of well-intentioned writing goes wrong. Strip the vocabulary and you often strip the mechanism with it: “eventually consistent” becomes “fast,” “at-least-once” becomes “reliable,” and the reader loses the one word that would have made them look up the failure mode. Keep the exact term, define it in a clause, then use it consistently. A reader who has to learn four terms to make a correct decision is better served than a reader who learns none and makes a wrong one.

Study the artifact: first principles and user capability

Two bodies of public work pull in useful opposite directions, and the editorial rule falls out of holding both.

Kelsey Hightower’s teaching artifacts work from the machinery up. Kubernetes The Hard Way makes the learner generate the certificates and start the control plane by hand, so that the abstraction they later use has a visible interior. The instructional bet is that a model of the mechanism transfers to failures nobody wrote a runbook for. The cost is time and tolerance: a manual build is a poor first hour for someone evaluating whether the thing is worth an afternoon.

Kathy Sierra’s work pushes from the other end. Her argument in Badass: Making Users Awesome is that people don’t adopt tools because the tools are good; they adopt them because of what they can now do that they couldn’t before, and the object of design attention should be the user’s growing capability rather than the product’s feature surface. Applied to explanation, that means the unit of a good page is a thing the reader can now do and verify, not a thing the system has.

Combine them and you get one editorial rule: reveal the mechanism required for the reader’s next correct decision, then give them a marked path to deeper resolution. Not all the machinery, and not none of it. The amount that changes what they will do in the next hour, plus a link for the hour after that.

Applied to the post-office talk, the rule produces a different fifteen minutes. Show the durable queue and one consumer. Then show a retry, on the screen, producing the same message twice — because that single state transition is what the billing team needed and what the metaphor concealed. Ordering guarantees, partition behavior, and dead-letter policy go in the linked explanation page, clearly signposted, where the team lands the day they need them.

The Explanation Stack

Any concept worth teaching should exist at five resolutions of the same picture. They are not five documents saying the same thing at different lengths; each answers a different question and each is the right entry point for a different reader.

One sentence — orientation. What problem does this solve, for whom, under what condition? The condition clause is the part usually missing, and it’s the part that saves people from evaluating something that was never meant for them. “A durable work queue for services that can tolerate a message arriving more than once” tells a reader in one line whether to keep reading.

One picture — relationship. Essential parts and flows, labelled with the names used everywhere else. Five to nine boxes. The picture’s job is to give the reader somewhere to hang every later detail; if the mechanism section introduces a component the diagram never showed, the diagram was drawn for the wrong audience.

Five minutes — mechanism. What state changes, what triggers the change, and where it can fail. This is the layer most content skips, jumping from diagram to tutorial, and skipping it is what produces users who can follow steps and cannot debug. Write it as a sequence of transitions with the failure branch attached to each: a message is accepted and persisted; a consumer leases it; the lease expires without an acknowledgement; the message becomes visible again — which is the point at which your handler needs to be idempotent.

Twenty minutes — guided action. The reader achieves a result and verifies it themselves. Verification is the load-bearing word. A tutorial that ends with “you should now see the dashboard” is asking for trust; one that ends with a command whose output the reader can compare against a printed expected value is giving them proof, and proof is what makes the next twenty minutes feel worth spending.

Deep reference — certainty. Exact behavior, every configuration key, limits, version compatibility, error codes. Complete and boring, optimized for someone who arrived from a search engine at 2 a.m. with a specific question and no interest in your narrative.

Resist the urge to put all five on one page. The five resolutions are a system connected by links, and each layer should end by naming the layer under it, so a reader who needs more resolution knows exactly where to click. The most common structural failure in developer documentation is not a missing layer — it’s five layers that exist and don’t reference each other, so readers who need depth conclude it isn’t there.

Diátaxis as a content contract

Daniele Procida’s Diátaxis framework separates documentation into four modes, and its value in practice is less as a taxonomy than as a contract: each page declares one job and refuses the other three.

Tutorial — learning-oriented. A guided experience where the reader’s goal is to acquire capability, and the author chooses the path. The author’s obligation is that the path works, start to finish, for a beginner.

How-to guide — task-oriented. The reader already has a goal and needs the steps to reach it in their own context. Assumes competence, states prerequisites, doesn’t teach.

Reference — information-oriented. An accurate description of the machinery, structured for consultation. Neutral in tone, complete in coverage, no narrative.

Explanation — understanding-oriented. Context, reasons, relationships, tradeoffs, alternatives considered. Discursive by design, and the mode most often absent entirely.

The distinction that makes the framework stick is the pair of axes underneath it: whether the reader is studying or working, and whether they need action or knowledge. Tutorials and how-to guides serve action; reference and explanation serve knowledge. Tutorials and explanation serve study; how-to guides and reference serve work.

Mixing modes fails in specific, recognizable ways. A tutorial interrupted by an exhaustive options table loses the beginner at step four, because the beginner cannot tell which of the eleven flags they were supposed to care about. A reference page carrying persuasion becomes untrustworthy for consultation — the moment “recommended” appears next to a config value with no stated condition, the reader has to evaluate your motives while debugging. An explanation wearing the clothes of a migration guide is the most expensive version: the reader follows it expecting a supported path and discovers halfway that they’ve been reading an essay about why the architecture changed.

Two practical moves. Put the mode in the page’s front matter and show it in the template, so that drift is visible in review rather than in a support ticket. And when a page is genuinely trying to do two jobs, split it and cross-link rather than negotiating a compromise, because the compromise version serves neither reader and both will tell you so.

Progressive disclosure, and the thing it must never hide

Present the essential choices first; reveal expert detail when it becomes relevant. In practice that means a quickstart with one supported path and no branches, a “common variations” section below it, and a reference link for the full surface.

The failure mode is using disclosure to postpone consequences rather than complexity. If a default silently disables retries, if a flag in the quickstart puts the reader in a configuration that can lose data, if the sample credentials work in production — that information belongs in the reader’s field of view at the moment they act, not two links away under Advanced. Progressive disclosure delays detail. It should never delay risk.

A useful test before you collapse a section behind a link or a toggle: if the reader never opens it, can they still be surprised in a way that costs them data, money, or a weekend? If yes, it isn’t advanced detail. It’s a warning that’s been misfiled.

Analogies with expiration labels

Analogies are one of the highest-leverage tools available for teaching an unfamiliar system, and they should ship with four things attached.

What maps. Name the specific correspondence you intend — “like a post office” is a gesture; “like a post office in that the sender doesn’t wait for the recipient” is a claim you can check.

What does not map. The part the composite scene got wrong. State it in the same breath as the analogy, before the reader has built anything on it: mail arrives once and roughly in order, and this system guarantees neither.

The decision the analogy supports. Analogies are for a purpose, and naming the purpose bounds the borrowing. This one supports “should my service call yours synchronously?” It does not support “how should I handle a duplicate charge?”

The point of replacement. Say what the reader must switch to the real model for, and where that model lives. “Once you’re writing a consumer, drop the post office and use the delivery semantics table — link.”

Say all four out loud in a talk. It costs about fifteen seconds and it’s the difference between a memorable image and a production incident with a charming origin story.

Words that move

Feature-first: “Our event-driven architecture provides asynchronous scalability through a decoupled broker.”

Three problems. Nobody learns what changes for them, the sentence describes the system’s properties rather than the reader’s new capability, and it contains no decision.

Capability-first:

When one service slows down, the others no longer have to wait for it to finish. They place work on a durable queue and continue. That improves isolation, but it introduces new decisions about delivery order, duplicate processing, retries, and visibility. The diagram shows where those decisions live.

The second version is longer and does considerably more work: it names the gain, names the cost as a set of decisions the reader now owns, and points at where the decisions are documented. A reader can act on that. A reader can also decide, correctly, that they don’t want it yet.

Change smells

• “Simple” turns out to mean prerequisites were omitted.
• The explanation opens with internal component names — the reader meets Orchestrator before they meet their own problem.
• Every concept gets a metaphor and none gets a state diagram.
• Advanced detail is hidden even when it changes risk.
• One page tries to teach a beginner, guide a task, document every option, and justify the architecture.
• Jargon was removed and precision left with it.
• The five-minute mechanism layer is missing everywhere, and support answers it repeatedly, by hand, in tickets.

Field tool: the Explanation Stack worksheet

Take one concept your users get wrong — pick it from support tickets rather than from your own sense of what’s hard — and fill this in. It fits on a page and it takes about an hour.

• Audience and prior knowledge:
• Decision they need to make:
• One-sentence orientation:
• One-picture parts and flow:
• Five-minute mechanism:
• Twenty-minute verified action:
• Deep-reference link:
• Primary tradeoff:
• Likely misconception:
• Analogy and expiration label:
• Term that must be defined:
• Evidence that the explanation worked:

Two lines do most of the diagnostic work. If you cannot state the decision they need to make, you are about to write a page organized around your system’s structure instead of the reader’s situation. And if evidence that the explanation worked is blank, you have no way to distinguish a page that teaches from a page that ranks.

Run the finished stack past someone who has the audience’s prior knowledge and not yours, and ask them to restate the mechanism and the tradeoff in their own words. Where their restatement is wrong is where your explanation is wrong. This is cheaper than every other method of finding out.

Measure it

Four signals indicate legibility rather than traffic. Whether learners can accurately restate the mechanism and the primary tradeoff — ask, in a workshop, an office hour, or a short survey after a tutorial. Whether the share of conceptually misclassified support questions falls, which is the clearest evidence that a mental model landed. Tutorial completion with correct verification, counted at the verify step rather than the last page. And navigation between the four modes: readers moving from tutorial to how-to to reference are following a path you built, and readers bouncing between them repeatedly are lost in a structure that looks organized to you.

Countermetric: page views. A page can be busy because it’s useful, because it’s confusing, or because something upstream is impossible to find. Traffic on a troubleshooting page is ambiguous news at best, and a rising graph there has closed more investigations than it should have.

Next

A legible explanation gets a developer to a correct model of what your system does. It doesn’t settle whether your claims about that system are true. The reader who now understands the mechanism will ask what it does under their load, on their version, with their data — and the answer has to be something they can run rather than something you assert.