Explaining anything: layers, analogies, and numbers

Senior engineers are, functionally, professional explainers: to juniors, to adjacent teams, to executives, to auditors, to the on-call at 3 a.m. via runbook. And explanation has craft the same way disagreement does: layered depth, analogies that declare their own limits, comprehension checks that do not condescend, and numbers phrased so they cannot be misheard. This chapter is that craft.

The three-depth rule

For anything you own, keep three explanations loaded:

  1. The headline (one sentence, anyone): "The ledger is the append-only history of every budget decision, so any bill can be explained after the fact."
  2. The mechanism (one minute, technical adjacent): "Every grant and spend is an event with an actor and a reason. State is never stored, only derived by replaying events, so the balance and the audit trail cannot disagree."
  3. The walkthrough (ten minutes, whiteboard, someone who will work on it): the actual data shapes, the failure modes, the why-nots of the alternatives.

The failure mode is owning only depth three. Asked "what's the ledger?" in an elevator, the depth-three owner starts with event schemas and gets cut off before reaching the point. Build the headline first; it is the hardest of the three to write and the one most people never do. The test: your headline should survive being repeated by a PM to a VP without you in the room.

Structure inside any depth: what, so what, now what. What it is, why the listener should care, what happens next or what you need. The same skeleton runs the demo narration in Chapter 21 and the incident update in Chapter 11; explanation is one genre wearing many costumes.

Analogy craft

Analogies are load-bearing in technical explanation, and they obey three rules:

  • Source domain must belong to the listener. Explaining event-sourcing as "like a bank ledger" works on everyone; explaining it as "like a blockchain without consensus" works only on people who did not need the analogy.
  • Declare the breaking point. Every analogy fails somewhere, and saying where is what separates teaching from misleading: "A cache is like keeping snacks at your desk instead of walking to the kitchen. The analogy breaks on invalidation: the kitchen never swaps the milk without telling you, but upstream data changes under your cache silently, and that's where all the bugs live." The breaking point is not a weakness of the explanation; it is the explanation, because the residue after the analogy fails is exactly the hard part of the concept.
  • Retire leaky ones. If listeners keep drawing wrong conclusions from your analogy, the analogy is a bug; fix it like one.

Checking comprehension without condescending

"Do you understand?" tests the listener and invites a defensive "yes." The professional forms put the burden on yourself:

  • "Where did I lose you?" (assumes you lost them; always safe)
  • "Want me to go deeper on any part, or is that the right depth?"
  • "That was a lot; which part should I say again differently?"
  • The reverse playback, for high stakes: "Can you say back what you're taking, so I know I explained it right?" (Framing the check as auditing your own explanation makes it painless to accept.)

And going the other way, when you are the listener: Chapter 22's targeted replay ("say the part after the cache again?") is exactly this move from the other chair.

Numbers that cannot be misheard

Numbers are where explanations silently fail, because number phrasing has traps that grammar does not flag:

  • Percent versus percentage points. The error rate going from 2% to 4% is a rise of two percentage points and of one hundred percent. Say whichever you mean, and when the stakes are real, say both: "it doubled: from two percent to four." A real meeting can spend ten minutes with half the room hearing "tiny change" and half hearing "doubled", and both halves are right.
  • "3x more" is ambiguous. "Three times as many" is clear (300 of the old 100); "three times more" is heard as either 300 or 400. Prefer "as many", or give both ends: "from 100 to 300."
  • Improved BY versus improved TO. "Latency improved by 40ms" and "improved to 40ms" describe different worlds. The safe pattern names both ends every time: "from 120 down to 80."
  • Baselines are not optional. "40% faster" than what, measured when, on which workload (Chapter 12's formula). In speech, the baseline goes first, because listeners anchor on the first number they hear.
  • Round aloud, exact in writing (Chapter 24), and mark the rounding: "call it a third" signals compression honestly; "33.4%" spoken aloud signals false precision and gets remembered wrong anyway.
  • Order-of-magnitude language for early estimates: "this is a tens-of-thousands-of-dollars problem, not a millions problem" is often all a decision needs, and refusing spurious precision is a seniority marker (Chapter 14's calibration, applied to arithmetic).

Don't be confused: simple and simplistic are opposites in disguise. Simple means the irreducible complexity was found and everything else removed: the highest compliment an explanation or design can earn. Simplistic means real complexity was amputated to make the story tidy: "the migration is just a rename" is simplistic if it ignores the two consumers who parse the old name. When someone calls your explanation simplistic, the repair is not more words; it is naming the complexity you skipped and saying why you skipped it: "I left out the replay path deliberately; it only matters during cutover, and I'll cover it there."

Explaining decisions, not just systems

The most consequential explanations are of choices: why this design, why not the obvious alternative, why now. The skeleton that works is the one Chapter 4 uses prospectively, run in reverse: constraint, options considered, tradeoff taken, evidence since. "We chose DynamoDB because the access pattern was pure key-value and ops headcount was zero; we knew we were giving up ad-hoc queries, and that bill arrived last quarter as the analytics workaround. Given today's team, I might choose differently, and the switching cost is the real question." That paragraph explains a system, an era, and a lesson in four sentences, and notice it contains no defensiveness: explaining a past decision is not defending it (Chapter 6's audit-versus-proposal distinction, from the answering side).

The anti-pattern is the explanation that is secretly a justification: selective evidence, missing alternatives, and "obviously" doing the load-bearing work. Rooms smell it, and it converts a technical explanation into a credibility question.

👉 Explanation aims at understanding; the next chapter aims at agreement. Arguing well: what evidence actually is, the fallacy field guide with polite counters for each, how to weigh a vivid anecdote against a boring dataset, and the highest-status move in engineering: changing your mind in public, gracefully. On to Chapter 26.