23 SCREENS · Displays that think for you
Let readers change the numbers.
You will learn how to write an argument whose numbers the reader can change, so they can test your claims instead of trusting them. It takes 7 minutes.
Test this argument
Here's a short argument about vaccines and outbreaks. Don't take its numbers on trust. Change them, and watch what the argument says next.
EXAMPLE · ILLUSTRATIVE NUMBERS · NOT MEDICAL ADVICE
Drag a dashed number sideways, use its arrow keys, or tap its - and + buttons.
Say each case of a disease infects 4 other people, in a group where nobody is immune. Then outbreaks shrink instead of growing once 75% of people are immune. Past that point, each case passes it on to fewer than one new person, on average.
What's R0, and is that number realistic?
R0, the basic reproduction number, is how many people one case infects on average when nobody is immune. It depends on the disease and on how people live and meet. The 4 here is an illustration, not a real disease.
Suppose the vaccine protects 90% of the people who get it. To get 75% of people immune, you need to vaccinate 83% of everyone.
What does "protects" mean in this model?
The model treats the vaccine as all or nothing: it fully protects some people from infection and does nothing for the rest. Real vaccines can also make illness milder or cut how much people pass it on. This model leaves that out.
Today, 70% of people are vaccinated. That leaves 63% of people immune, so each case infects 1.5 others on average, and the outbreak grows. You're 13 points short of the 83% target.
Out of every 1,000 people, 630 are protected, 70 were vaccinated but aren't protected, and 300 weren't vaccinated.
Where does this model stop being true?
The math is the classic threshold, 1 minus 1/R0, divided by how well the vaccine protects. It assumes:
- Everyone mixes with everyone else evenly. Real people mix mostly within their own groups. In one example from Elbasha and Gumel (R0 of 2.5, a vaccine that protects 95%), allowing for that drops the coverage needed from 63% to 40%.
- Protection lasts. If it fades, coverage has to keep rising to hold the same share immune.
- Nobody is immune from past infection, and R0 is the same everywhere.
So use it to see how the numbers relate, not to set a real target.
Did you find where it breaks? Push the vaccine's protection below the threshold, and the claim turns into "more than everyone." Push R0 below 1, and there's no threshold at all.
What just happened
You didn't read that argument. You tested it. Bret Victor, who named the method, starts his 2011 essay with a question: "What does it mean to be an active reader?" His answer: "An active reader asks questions, considers alternatives, questions assumptions, and even questions the trustworthiness of the author."
A page can let readers do that. Victor names three parts, and the argument above uses all three:
1. A reactive document. "A reactive document allows the reader to play with the author's assumptions and analyses, and see the consequences." Above, that's the dashed numbers and every sentence that follows them.
2. An explorable example. "An explorable example makes the abstract concrete, and allows the reader to develop an intuition for how a system works." Above, that's the 200 dots: the percent, as people.
3. Contextual information. "Contextual information allows the reader to learn related material just-in-time, and cross-check the author's claims." Above, that's the notes under each paragraph, where the assumptions live.
This isn't a chart next to the text. The Feynman lesson shows a cruise-control simulation as a chart beside its words. Here the words are the model: the numbers in the sentences are its inputs and its results.
In 2024, Victor added a note. The term had come to mean "any article with interactive pictures." What he meant was "a written argument whose assertions are backed by explorable computational models, whose facts, assumptions, and calculations are all visible and editable." In his words: "The reader's role is not to believe, but to critically evaluate, rebut, and come to a broad understanding."
Watch it built
The clip starts with the same argument as plain text. Watch which numbers change when one assumption moves, and the moment a claim flips.
THE NAME FOR IT
Explorable Explanations
Bret Victor · Explorable Explanations (worrydream.com, 2011)
Write the argument as a live document. The reader can change the author's assumptions, and every claim that depends on them updates in place.
Try to break it
An explorable argument has to stay true at every setting a reader can reach, not just the one you wrote it for. So this page tests itself. Each time it's built, it nudges each live number to see which claims it drives, then sets the numbers to the edge cases and checks what the page says:
| Live number | Range | Claims it drives |
|---|---|---|
| Cases each case causes when nobody is immune (R0) | 0.5 to 20 | the threshold, the coverage needed, today's verdict |
| Share of vaccinated people the vaccine protects | 30% to 100% | the coverage needed, today's verdict, the 1,000 people |
| Share of people vaccinated today | 0% to 100% | today's verdict, the 1,000 people |
| Edge case | R0 · protects · vaccinated | What the page says | Check |
|---|---|---|---|
| The example | 4 · 90% · 70% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 63% of people immune, so each case infects 1.5 others on average, and the outbreak grows. You're 13 points short of the 83% target. | Pass |
| R0 below 1 | 0.8 · 90% · 70% | Then it dies out on its own, even with nobody immune, because each case passes it on to fewer than one new person. That leaves 63% of people immune, so each case infects 0.3 others on average, and the outbreak shrinks. | Pass |
| R0 exactly 1 | 1 · 90% · 70% | Then it can't grow, even with nobody immune, because each case passes it on to just one new person. That leaves 63% of people immune, so each case infects 0.4 others on average, and the outbreak shrinks. | Pass |
| Vaccine too weak | 4 · 70% · 70% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 49% of people immune, so each case infects 2.0 others on average, and the outbreak grows. No amount of coverage closes the gap. | Pass |
| Coverage meets the target | 4 · 90% · 90% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 81% of people immune, so each case infects 0.8 others on average, and the outbreak shrinks. That meets the 83% target. | Pass |
| Exactly at the threshold | 4 · 100% · 75% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 75% of people immune, so each case infects 1.00 others on average, and the outbreak holds steady. That meets the 75% target. | Pass |
| Nobody vaccinated | 4 · 90% · 0% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 0% of people immune, so each case infects 4.0 others on average, and the outbreak grows. You're 83 points short of the 83% target. | Pass |
| A very contagious disease | 20 · 100% · 100% | Then outbreaks shrink instead of growing once 95% of people are immune. That leaves 100% of people immune, so each case infects 0.0 others on average, and the outbreak shrinks. That meets the 95% target. | Pass |
| Everyone vaccinated, perfect vaccine | 4 · 100% · 100% | Then outbreaks shrink instead of growing once 75% of people are immune. That leaves 100% of people immune, so each case infects 0.0 others on average, and the outbreak shrinks. That meets the 75% target. | Pass |
Run when this page is built, with the same functions the page uses. All 9 edge cases pass, and the three groups of people always add up to 1,000.
That's the hidden cost of the method. A fixed paragraph only has to be right once. A live one has to be right everywhere.
TAKEAWAY
Don't ask readers to trust your numbers.
Let them change them.
Build this way
- Find the claim. Write the one sentence you want the reader to accept, with its numbers.
- Find the assumptions. Which numbers did you choose, and which did you calculate? The chosen ones become live inputs.
- Write the model as code. Every calculated number comes from it. No number in the text is typed by hand.
- Write each claim for every case. If a result can cross a line (above or below 1, more than 100%), the sentence has to change with it.
- Mark what's live. A reader should see at a glance which numbers they can change. Make them work with a mouse, a keyboard and a thumb.
- Put the assumptions next to the claims. Say what the model leaves out, right where it matters.
- Test the edges. Set every input to its lowest and highest value and read the page. Every sentence must still be true.
- Make it work without the code. With scripts off, the page shows the example numbers as plain text.
Ask your agent
Turn the claim below into an explorable explanation (Bret Victor, "Explorable Explanations", 2011), as one self-contained HTML file. 1. Write the argument as two to four short paragraphs of plain prose. 2. List the assumptions behind the claim. Make each chosen number a live input in the text that the reader can drag, change with arrow keys, or step with - and + buttons. Give each a sensible range. 3. Write the model as one JavaScript function. Calculate every other number in the text from it. Don't type any result by hand. 4. Write each sentence that states a result so it stays true at every input value. If a result crosses a line, such as above or below 1, or over 100%, change the sentence. 5. Add one small picture that shows the result concretely, and short notes that say what the model leaves out. 6. With JavaScript off, show the default numbers as plain text. 7. Finally, list every input, the sentences it changes, and what the page says at each input's minimum and maximum. Don't invent data. If the claim needs a number you don't have, make it an input and label it as an assumption. Claim: [paste here]
What good output looks like: you can push every number to its limit and every sentence still reads true, and you can say which assumption the claim depends on most.
Sources
- Bret Victor, "Explorable Explanations" (March 10, 2011, with a postscript from 2024), on worrydream.com. The quotes above are from the essay and its postscript. Victor's own reactive document there is about a ballot measure on California state parks. He built it with Tangle, his JavaScript library. The source has a typo in "consequences", corrected here.
- Bret Victor, "Up and Down the Ladder of Abstraction" (October 2011), on worrydream.com: an explorable that moves between levels of abstraction.
- The herd immunity math: Elamin H. Elbasha and Abba B. Gumel, "Vaccination and herd immunity thresholds in heterogeneous populations," Journal of Mathematical Biology 83 (2021), open access. They give the classic threshold, 1 minus 1/R0, divided by vaccine efficacy, and note that it assumes "a homogeneous, well-mixed population." See also Paul Fine, Ken Eames and David L. Heymann, "'Herd immunity': a rough guide," Clinical Infectious Diseases 52, no. 7 (2011).
- The numbers on this page are illustrative, not a real disease or vaccine, and not medical advice.