Visual examples should earn their space

A visual earns its space when it lets the reader predict the next step.

For matrix multiplication, the reader should predict which dimensions match. For backpropagation, which value flows backward. For a state machine, which transition is legal. For an agent workflow, where approval blocks action.

“Input -> model -> output” is a useful scratch note and usually a weak article visual. A better retrieval diagram names the work:

query
  -> embed query
  -> retrieve candidate chunks
  -> filter by permission
  -> rerank by freshness
  -> assemble answer context

Now the reader can see where permission and stale-source bugs enter.

Good learning visuals change one variable:

before threshold:
scores: [0.91, 0.72, 0.43, 0.12]
kept:   [0.91, 0.72]

after threshold increases:
scores: [0.91, 0.72, 0.43, 0.12]
kept:   [0.91]

Interaction can help, but a slider is not automatically an explanation.

Architecture diagrams are especially bad at time. If retries, queues, delays, or review matter, use a sequence:

assistant proposes edit
user reviews diff
tool applies patch
checks run
result is recorded

Show the failures too: an ambiguous point, a sync conflict, a disabled form, or a filtered retrieval candidate. Ask what sentence can be removed because the visual now carries it.

Every visual needs an accessible text path. The best example leaves the reader with a small mental simulator: a prediction about a shape, threshold, transition, or failure.