Why examples beat descriptions

1. The principle

Descriptions live in your head. Examples live on the page.

Anything you can describe in words (write in our team's voice) you can also show with examples (here are three of our team's existing posts). When you describe, you commit to articulating the rule. When you show, you let the rule emerge from the cases. Show usually beats describe — by a wide margin.

The mechanism is straightforward: a model trained on patterns will pattern-match. Showing it three real cases gives it three real patterns. Describing the rule in prose gives it your guess at the rule, and your guess is almost always less accurate than the actual cases that led you to it.

2. The trap — articulating style

The clearest case where showing wins: style. Style is a fingerprint nobody can fully articulate. Try to describe your team's commit message style and you'll end up with something like "short, imperative, conventional commits style." That's directionally right and operationally useless. Three real examples land it instantly.

Write a commit message for this diff in our team's style — short, conventional, imperative voice.

[diff]

Write a commit message for the diff below. Match the style of these three real ones:

fix(auth): clear stale session cookies on logout
refactor(api): collapse duplicate handler in /users
feat(billing): retry failed Stripe webhooks for 24h

[diff]

The described version produces something like your style. The shown version produces your style — including the prefix scopes, the parenthetical, the verb mood, the level of detail. None of which you articulated.

3. When examples are the only way

There are some kinds of intent you literally can't describe in prose without losing fidelity. Examples include:

• Tone. Sarcastic-but-warm. Direct-but-not-rude. Conversational-but-precise.
• Format conventions. Indentation rules. Trailing comma rules. How long is "too long" for a section.
• Domain-specific patterns. What a good PR description looks like in your team. What a sensible test case looks like.

If you've ever found yourself adding clause after clause to a description ("but not too X, and not too Y, more like..."), that's a signal you should be showing instead. Stop describing. Pick two examples that hit the target and one that misses, and label which is which.

4. Try it