eli5 — explain it to someone who knows nothing
The topic is whatever the user named. With no topic named, it is the one the conversation is already
on. The audience is someone with zero background: no vocabulary, no context, no patience for a
definition that needs another definition.
The contract
- A page, not a paragraph. The output is one self-contained HTML page, big visuals first, words
second. Open it when it is written.
- Picture carries the idea, words label it. If the page still makes sense with the text removed,
it is working. Aim for a caption per picture, not a paragraph per picture.
- Everyday objects only. Compare to things a person has physically handled: boxes, keys, queues
at a counter, post, a light switch. Never explain one unknown with another unknown.
- Zero jargon, and zero smuggled jargon. No term appears without being shown first. "It caches"
is jargon; "it keeps a copy nearby so it doesn't have to walk back" is the same fact.
- Simple, never false. When the simplification would make something untrue, say what got left
out, in one line, at the end. A comfortable lie is worse than a hard truth.
- No condescension. Simple words, adult tone. The reader is new to the topic, not a child.
The shape of the page
one sentence: what this thing is, in words a stranger would use
big picture 1 : the thing, drawn
big picture 2 : the thing doing its job, step by step
one line : the part people get wrong
one line : what this explanation left out (only if it left something out)
Three to five visuals is the whole page. Inline SVG or plain HTML boxes beat any chart library here:
the drawing has to be readable on a phone, at a glance, with no legend to study.
open path/to/eli5-<topic>.html
Anti-patterns
| Anti-pattern |
Why it fails |
Do this instead |
| Define a term with two more terms |
The reader loses the thread on line one |
Show the thing, then name it |
| A wall of text with one decorative image |
That is a blog post with a picture |
Picture first, caption second |
| "Imagine you're a packet travelling…" |
Cute framing, still abstract |
Compare to an object the reader has held |
| Simplify until it is wrong |
The reader now has to unlearn it |
Keep it true and name what you dropped |
| Baby talk, emoji, exclamation marks |
Talks down to the reader |
Plain adult words, short sentences |
| Five diagrams of the same idea |
Repetition reads as padding |
One picture per genuinely new idea |
Where this ends
- Someone already following the conversation who needs the shape of one mechanism:
show-me.
- A structured curriculum with exercises, assessment and progression:
course-builder.
- Documentation an informed reader will keep coming back to:
technical-writing.
- Making an existing text sound human rather than simpler:
bro.
1---2name: eli53description: Use when a topic must be explained from zero to someone who knows nothing about it: one page, big pictures, very few words, everyday analogies, no jargon and nothing assumed. NOT the smallest in-conversation visual for someone already following (that is `show-me`), NOT a course with exercises (that is `course-builder`).4---56# eli5 — explain it to someone who knows nothing78The topic is whatever the user named. With no topic named, it is the one the conversation is already9on. The audience is someone with **zero** background: no vocabulary, no context, no patience for a10definition that needs another definition.1112## The contract13141. **A page, not a paragraph.** The output is one self-contained HTML page, big visuals first, words15 second. Open it when it is written.162. **Picture carries the idea, words label it.** If the page still makes sense with the text removed,17 it is working. Aim for a caption per picture, not a paragraph per picture.183. **Everyday objects only.** Compare to things a person has physically handled: boxes, keys, queues19 at a counter, post, a light switch. Never explain one unknown with another unknown.204. **Zero jargon, and zero smuggled jargon.** No term appears without being shown first. "It caches"21 is jargon; "it keeps a copy nearby so it doesn't have to walk back" is the same fact.225. **Simple, never false.** When the simplification would make something untrue, say what got left23 out, in one line, at the end. A comfortable lie is worse than a hard truth.246. **No condescension.** Simple words, adult tone. The reader is new to the topic, not a child.2526## The shape of the page2728```text29one sentence: what this thing is, in words a stranger would use30big picture 1 : the thing, drawn31big picture 2 : the thing doing its job, step by step32one line : the part people get wrong33one line : what this explanation left out (only if it left something out)34```3536Three to five visuals is the whole page. Inline SVG or plain HTML boxes beat any chart library here:37the drawing has to be readable on a phone, at a glance, with no legend to study.3839```bash40open path/to/eli5-<topic>.html41```4243## Anti-patterns4445| Anti-pattern | Why it fails | Do this instead |46| --- | --- | --- |47| Define a term with two more terms | The reader loses the thread on line one | Show the thing, then name it |48| A wall of text with one decorative image | That is a blog post with a picture | Picture first, caption second |49| "Imagine you're a packet travelling…" | Cute framing, still abstract | Compare to an object the reader has held |50| Simplify until it is wrong | The reader now has to unlearn it | Keep it true and name what you dropped |51| Baby talk, emoji, exclamation marks | Talks down to the reader | Plain adult words, short sentences |52| Five diagrams of the same idea | Repetition reads as padding | One picture per genuinely new idea |5354## Where this ends5556- Someone already following the conversation who needs the shape of one mechanism: `show-me`.57- A structured curriculum with exercises, assessment and progression: `course-builder`.58- Documentation an informed reader will keep coming back to: `technical-writing`.59- Making an existing text sound human rather than simpler: `bro`.
ericrisco