One page, one question

The strongest explainers answer a single question and stop. "How does a brake caliper work?" is one page. "How disc brakes work, plus how to change pads, plus brake fluid types" is three pages pretending to be one. When a topic starts to sprawl, split it and link the parts — it is better for the reader and better for search.

Let the diagram own the space

The picture is the argument. It should be the largest, calmest element on the page, with the prose arranged to support it rather than compete. A two-column layout — wide diagram on one side, a short parts list and the core principle on the other — keeps the eye moving between the two without a scroll marathon.

A layout that keeps the diagram in charge H1 + one-line summary Inline SVG diagram largest, calmest element on the page view toggle core principle one short paragraph parts list, hover to highlight
Figure 1 — Diagram first, support text second. The side column never grows into a second article.

Labels are content, not decoration

Every label on the diagram is a word the reader — and the search engine — gets to read. Write labels as real text in the SVG, not as outlined shapes, and keep the words short and concrete: the name of the part, not a paragraph about it. Tooltips and hover cards can add detail, but they never replace the visible label.

  • Contrast at or above 4.5:1. Small grey labels are the usual offender; darken them until they pass.
  • One name per part. Use the same term in the diagram, the list and the prose, or readers will hunt for a match that does not exist.
  • No label needed twice. If the drawing implies it, do not also annotate it.

Controls should almost disappear

The best interactive page feels like a diagram that happens to respond, not a machine with a control panel. Keep the chrome to a minimum: a zoom or fit toggle, a way to reveal the parts, and nothing else. Avoid play, reset, settings and mode buttons unless the content genuinely cannot be understood without them.

Where interaction does exist, make it forgiving. Hovering a part should highlight it; hovering the matching list row should highlight the same part; clicking should not destroy the reader's place on the page. The rule of thumb: every control earns its space by making the explanation clearer, or it goes.

Work without JavaScript first

Build the page so that with JavaScript switched off it is still a complete article: a diagram with labels, a written explanation and an FAQ. Then layer the interaction on top. This is not only kind to readers on poor connections — it is exactly how search crawlers and many assistive tools first meet the page. If the page only works with scripts, it is not finished.

Bottom line: one question, a dominant diagram, labels worth reading, controls that stay quiet, and a no-JS page that already explains everything. Ship that, and the interaction is a bonus rather than a crutch.