Lead With a Worked Example, Then Explain

A technical-writing pattern where you have Claude open with a concrete, runnable example — the smallest real case — and only then generalise into the rule, rather than leading with abstract description.

Readers learn a new concept by anchoring it to a concrete case; an abstract definition with nothing to attach to slides off. Leading with a worked example gives the explanation a place to land — the reader already has the picture, and the generalisation just names what they've seen. It also forces the writing to be correct, because a real example either works or it doesn't, unlike hand-wavy prose.

Documentation, tutorials, API references, how-tos — anywhere the reader's goal is to do something. The more procedural or unfamiliar the topic, the more an example-first structure helps.

Conceptual or reference material where the reader needs the full model before any instance makes sense, or where a misleadingly simple example would create false confidence. Some ideas genuinely need the theory first.

Write the docs for <feature/concept> example-first. Open with the smallest concrete, runnable example that shows it working. Then explain what the example demonstrates, then state the general rule, then note the important edge cases. Keep the example real and correct — no pseudo-code that wouldn't actually run. Audience: <who> at <skill level>.

Documenting a config option, Claude opens with a five-line snippet that sets it and shows the effect, then explains the field, then lists the valid values. A reader copies the snippet, sees it work, and reads the explanation already understanding what it's talking about.

Have Claude build a single running example that grows through the doc — start minimal, then extend the same example to show each additional feature — instead of a fresh disconnected snippet per section. One evolving example is far easier to follow than a dozen unrelated ones.

• Leading with an example so contrived it teaches the wrong mental model.
• Shipping example code that doesn't actually run — a broken snippet destroys trust in the whole doc.
• Following the example with the exact same information in prose, doubling the length without adding anything.