Stop explaining the same thing twice

Imagine explaining a checkout timeout to a colleague in a paragraph like this:

A checkout request may reach a service and create an order before the reply is lost. The browser can therefore time out even though the operation succeeded. A timeout alone does not prove failure. Inspect the existing request or retry using the same supported operation identity rather than treating a missing reply as permission to create a new purchase.

Every sentence is accurate. The reader still has to assemble the sequence in their head, and shortening the part they don’t understand won’t do that for them.

Give your AI the missing inference and ask for three ways to show it. Keep the representation that helps someone answer the next question. The figures here are original and code-driven, and the examples are synthetic. I am not claiming a learning speedup.

Don’t shorten the part they don’t understand; show the relationship

Put the sequence where the reader can inspect it.

The missing reply is not the missing order. This is the work I want the AI to take over: searching for a representation that makes the difficult inference available. It shouldn’t return another headline saying the explanation is clear, or a decorative picture of a confused person. A reader should be able to point to the relationship that answers the question.

Make the limit impossible to miss

A ten-second job has two seconds that cannot be divided. Add workers and the divisible part changes while the limit stays put.

Three choices make that figure work, and they are the ones I’d ask an agent to make:

1. Identify: one job, two kinds of work. Keep the distinction next to the object, so the reader doesn’t hunt through a distant legend.
2. Change: add workers without moving the baseline. Only divisible work shrinks; with four workers it goes from eight seconds to two. A stable position makes the changed relationship easy to follow.
3. Infer: the part that stays explains the ceiling. Two seconds remain. A paused explanation should still make its point.

T(n) = s + p/n
S(n) = (s+p)/(s+p/n)

Tversky and colleagues warn that animation can be too fast or complex, and that some comparisons give the moving version extra information. That is why this page keeps the point visible before interaction. Motion helps expose a change; it does not certify comprehension.

A crowd of outputs can hide a small evidence base

Take 1,000 generated summaries, each an authored record with a source ID. Drawn as a crowd, they look like 1,000 pieces of support. Group the same records by the source they cite and there may be only 10 sources behind all 1,000 summaries. Nothing new was measured; something already present became easier to see.

Grouping reveals repeated attribution. It does not prove the sources are independent, true or representative. No personas, eye movements or confidence percentages are inferred from the records.

Drawing a thousand people looking at a screen would show scale. Keeping record identity while regrouping by source shows why the scale might mislead. That changes the operation the reader must do, rather than decorating the topic.

Ask for three different mechanisms

A timeline shows sequence. An aligned comparison reveals a difference. A controllable model exposes what changes when an assumption changes. Three colour schemes for the same paragraph are not three mechanisms. The request I’d give a model runs through five questions:

1. Audience: what do they already know? Do not explain HTTP from scratch to a backend engineer.
2. Obstacle: what inference is missing? “Timeout” is being mistaken for “nothing happened.”
3. Alternatives: choose different structures. Sequence, comparison and counterfactual, not different colours.
4. Implementation: build one inspectable version. Correct labels, units, relationships and a static fallback.
5. Check: ask a new question. Can the reader use the idea without your explanation?

The model needs room to search for a better representation. It also needs a reason to reject a clever-looking one. Ask which mental step disappears, what the picture omits and where the analogy fails. Keep the shortest adequate path to understanding, which is not necessarily the shortest text.

Count the understanding you enable rather than the attention you hold

A longer visit can mean interest or confusion. A fast answer can be confidently wrong. Ask a new question, then keep correctness, time and confidence separate. Try one:

A booking request times out. You have not inspected the service. What do you know?

1. The booking failed.
2. The booking succeeded.
3. The reply is missing; the booking outcome is still unknown.

When is a reusable explanation worth building? A rough model: net person-time equals the people who use the explanation, times the minutes each avoids, minus the extra design and maintenance time. With 50 readers, an assumed 3 avoidable minutes each and 60 extra minutes, that is 50 × 3 − 60 = 90 minutes saved, if the assumed benefit is real. The avoidable minutes may be negative, because a poor visual can make the task harder. These inputs are assumptions, not measured reading speeds or an established learning effect, and accuracy and access requirements remain constraints. It is a reason to measure and reuse good explanations, not a forecast that this article saves time.

Minimise time to a correct, unassisted inference
subject to accuracy, retained understanding and access constraints.

Research Debt argues for investing in the representations that later readers reuse. That is a strong reason to treat explanation as engineering work. It is not a measured return on any particular animation.

Your next doc can contain a working explanation

You can test this on a question your team already asks twice. No made-up deadline is needed.

The design direction isn’t new. Bret Victor’s explorable explanations (2011) make the idea something to manipulate; that is an original essay, not evidence of our learning outcomes. TheoremExplainAgent (2025) separates the explanation plan from its code through a staged process; it is a system demonstration, not a universal promise of better teaching. The step I’d take at the next review is to give the agent the question people keep asking, and ask for a representation, a counterexample and a check instead of “make it pop.”

The paragraph, the diagram and the animation are candidates. None earns its place by looking finished; the useful one makes the next inference possible.

My bet is that a working explanation stops you rebuilding it in every conversation. If it doesn’t, keep the simpler version. Originality is only useful here when it changes what a reader can correctly understand or do.

For coding agents: the explanation brief

The brief asks for a working explanation, alternative mechanisms, source fidelity and a new-case check. You get something a reader can inspect. The agent gets a precise confusion to resolve. The remaining question is whether people actually understand it better.

# Build an explanation the reader can use—not just admire
Audience: someone who understands full-stack development and applied AI.
Decision to enable: after a request times out, decide what can and cannot be inferred about the remote outcome.
Existing confusion: no reply is mistaken for no operation. State that exact gap before drafting.
Facts: a request can be recorded before its reply is lost. An unconfirmed reply is not proof of either success or failure. Safe retry requires the same supported operation identity.
Create three genuinely different representations: an aligned before/after comparison; a sequence that preserves event identity; a counterfactual control. Do not return three colour variations or decorate paragraphs with generic pictures.
Keep the conclusion legible in the initial static frame. Use scroll or motion only to reveal sequence, dependency or a changing relationship. Provide direct controls, reduced motion and a no-JavaScript reading path. Do not hide caveats needed to interpret the figure.
Check code, labels, units, source fidelity and edge cases. Distinguish measured facts from illustrative quantities and assumptions. A heatmap is not eye tracking unless it comes from eye tracking.
Then propose a new example the reader has not seen. Collect correctness and uncertainty before explaining the answer. No leading think-aloud prompt in the unassisted condition.
Return: one working HTML explanation; two small alternative representations; the assumption ledger; source links; tests; the remaining human-validation question; all build and review effort.
Do not claim faster understanding from aesthetics, a click, time-on-page or synthetic personas. Keep a simpler static candidate when it works equally well.