Structure an explainer: how it works

How it works

The order of a mechanism is the order the reader will follow it in. This structure covers four common cases: a process (steps in sequence), a mechanism (parts that act on each other), a cause chain (this leads to that) and a comparison (two or more things against the same criteria). If you have not chosen a format yet, start with the explainer skill.

The shape

1. Purpose. What it is for, or what question it answers, in one sentence.
2. The parts. Name the few things involved, and say what each one is. No more than about six.
3. The flow. Walk through it in order: what happens first, what it triggers, what comes out.
4. A worked example. Run one concrete case through the flow with real numbers or names.
5. What goes wrong. The common failure and how it shows up. This is where understanding becomes usable.

For a comparison, replace 2 and 3 with the criteria (what matters), then each option against each criterion, one criterion at a time, then a verdict.

Template

Purpose:  <What it is for.>
Parts:    <The few things involved, one line each.>
Flow:     <Step 1, then step 2, then step 3, each one caused by the last.>
Example:  <One case run through the flow.>
Failure:  <What goes wrong and how to notice it.>

Example, for a web request:

• Purpose: getting a page from a server to your screen.
• Parts: browser, DNS, server, cache.
• Flow: the browser asks DNS for an address, connects to the server, receives the page, and caches what it can.
• Example: loading one real page, with timings.
• Failure: a stale cache shows an old page.

How to write it

1. Name the parts first, once, and use the same names throughout. Do not rename a part to avoid repetition.
2. Number the steps if the order is fixed. In prose, link them with the cause ("which makes...", "so...") rather than "then".
3. Show what moves between the parts: data, money, a signal. Arrows in the text ("A sends X to B") are enough.
4. Choose an example the reader can imagine, and run it all the way. Keep its numbers small.
5. For comparisons, compare on the same criteria in the same order. A table is the right shape for the final summary.
6. Finish with the failure case and a one-line summary of the flow.

Pair it with a format

• Annotated walkthrough: the best match when there is a diagram or code to point at. The notes follow the flow.
• Scrollytelling: when the process happens over time or in stages and a diagram can light up one stage at a time. One step per stage.
• Page furniture: a timeline for the sequence, define for the parts, a compare for before and after.
• Open with Situation, Complication, Resolution if the reader needs to see why it matters, or with Layered when the reader is new to the topic. If there was drama in how it happened, use And, But, Therefore instead.
• Code and formulas in the flow follow the rules in math-and-code-blocks.

Mistakes

• Starting with the details of one part before the reader knows the others exist.
• Steps that are a list of nouns, not a chain of causes.
• A diagram or example that appears only at the end. Put it where the reader first needs it.
• Leaving out the failure case, which is what readers will remember.