# Explanation Patterns — Complexity → Simplicity How to structure the *content* of an explainer. The visual grammar file covers *how it looks*; this covers *what order ideas arrive in and in what clothing*. --- ## 1. The Ladder of Abstraction (Bret Victor) Move deliberately between concrete and abstract. Novices must START at the bottom (a single concrete instance running before their eyes) and be *walked* up. Experts write explanations top-down (definition → properties → examples) because that's how the knowledge is stored once compressed — it is the exact wrong order for acquiring it. **Pattern per chunk:** one concrete running instance → vary one thing → notice the pattern → NAME the pattern (the abstraction arrives last, as a label for something already understood). ## 2. Analogy discipline - **Source domain = reader's world.** Pull from their profession, hobbies, prior chunks. An analogy to something they half-know explains nothing. - **Map explicitly.** Don't just say "it's like a post office" — show the mapping table/diagram: envelope→packet, address→IP, sorting facility→router. Unmapped analogies feel clever and teach nothing. - **Break it on purpose.** Every analogy has a cliff. State it: "here's where the post office picture lies to you: packets can arrive out of order and duplicated." The break-point is often the most instructive moment — it's where the topic's *actual* nature lives. - **One load-bearing analogy per explainer.** Secondary micro-analogies are fine for individual chunks, but the recap compresses back to the one spine analogy. Multiple competing spine analogies fragment memory. ## 3. The Feynman loop (as a feature, not advice) Understanding is verified by generation, not recognition. Build it in: - **Say-it-back prompt:** one sharp question ("Explain to a friend why X can't just Y"), answered out loud, then a `reveal the answer` button showing a model answer for self-comparison. Never framed as correction. - **No text box, not even as an illustration.** Add one `copy follow-up prompt` button and one line naming the file's limit. - **Reality check:** 4–6 one-tap questions, ~one per chunk, answered from memory. A tap locks the question, marks the right answer, and reveals a one-line *why* (the why is the teaching). Include one transfer question about a case not shown on the page. Verdict names which chunks to re-read, and names the effect rather than the reader ("recognition beat recall, normal on a first pass"). ## 4. Worked example → completion → generation For procedural topics (algorithms, calculations, protocols): show one fully worked example with every step visible → second example with 1–2 steps blanked for the reader to predict → optionally a fresh case. Never jump from "here's the rule" to "apply the rule" — the worked example IS the explanation. ## 5. Pre-training (name the cast first) For any MECHANISM/SYSTEM with >3 parts: one chunk introduces the cast — each part's name, look (consistent color/icon that persists through the whole explainer), and one-line job. Only then show interaction. Consistent visual identity per part across all chunks is mandatory: the resolver is *always* the amber hexagon. ## 6. Mystery structure Open with the puzzle, not the answer. "Your bank balance is a lie — there's no number in a vault anywhere. So what IS it?" beats "A ledger is...". Each chunk can end on a micro-cliffhanger that the next chunk resolves ("...but this creates a new problem: who watches the watcher? →"). Curiosity gaps are the sustainable fuel; manufactured suspense about trivia is not — the gap must be real. ## 7. Contrast pairs / near-miss examples Concepts are learned at their boundaries. Show the thing AND the almost-thing: "this IS recursion / this LOOKS like recursion but is iteration — spot the difference" with a synced side-by-side. Misconception-first is a power move: state the popular wrong belief, let the reader hold it for a beat, then break it visibly. (Debunk explicitly — never leave the misconception as the last-seen frame.) ## 8. Frequencies, not probabilities "3 out of every 100 people" with 100 animated dots, 3 highlighted — never "3%". For conditional probability (medical tests, spam filters), the natural-frequency tree with dot populations is the ONLY reliably understood format. Percentages of percentages are where lay understanding goes to die. ## 9. Scale bridging Humans can't intuit anything beyond ~3 orders of magnitude. Bridge with a familiar-object ladder: each rung a 10× step anchored to a known thing (grain of rice → ant → coin...). For time: compress to a calendar year or a day ("if Earth's history were one year, humans arrive at 11:58 PM Dec 31"). Money: convert to per-person, per-day terms. ## 10. Reactive documents (Victor) The strongest form: assertions the reader can *test*. Any sentence containing a number the reader might doubt or wonder about becomes a draggable number that recomputes downstream consequences live ("If you save ⟨₹10,000⟩/month at ⟨12%⟩, in ⟨20⟩ years..."). Guide attention: an explorable with no guidance is a toy; pair every interactive with a suggested experiment ("try setting the rate to 0 — notice what survives"). ## 11. Spaced structure inside one page You can't control when the reader returns, but you can echo: key idea from chunk 2 reappears briefly as the foundation of chunk 5 ("remember the gossip chain? now each gossip gets a notebook —"). Each echo is a retrieval event. The recap is the third touch. Three touches in one page ≫ one touch. ## 12. Sequencing template (default spine) 1. **Hook** — the phenomenon, live, surprising (cold open). 2. **Stakes** — why this matters to *this* reader, one breath. 3. **Cast** — pre-train the parts (if >3 parts). 4. **Mechanism I** — spine analogy + first half of the machine, interactive. 5. **Checkpoint** — prediction game. 6. **Mechanism II** — second half; break the analogy where it breaks. 7. **Edge / misconception** — the near-miss, the popular wrong belief, or the failure mode. 8. **Recap** — spine analogy in one line, vivid anchors, explain-it-back, rabbit holes. Compress or expand (5–9 chunks) but keep the shape: hook first, cast before mechanism, checkpoint mid, recap last.