Operationally useful docs

The one rule everything else serves: no reader should finish a doc and think "I get what this is, but I don't know how to make it useful."

If a page leaves a reader nodding and then unable to act, the page failed. Description without action is the failure mode I care about. A paragraph can be descriptively true and operationally useless at the same time.

The deletion test

For any section, delete every fenced code block. If the section still teaches something useful, the section is mislabeled — it's an explainer, not a how-to. Either add code, or move the prose to an explanation page.

What this rules out

Sentences like "The owed-reply filter is a powerful way to find threads where the user is the bottleneck. It integrates with the saved-search system." — descriptively true, operationally useless. The replacement is a real invocation the reader can paste and run:

mxr saved add owed 'is:owed-reply'

Same idea, but the reader can act.

Why this is the load-bearing principle

Every other rule I keep — runnable code per section, recipes over reference restating, mutations shown dry-run first — is a tactic. This is the goal. When tactics conflict, the goal wins.

See also

• How I Write Software Docs — the full synthesis
• Documenting Domain-Specific Knowledge — Calderone's adjacent take: docs should help the audience get their job done, not archive everything knowable
• A Recipe Solves a Goal — the structural antidote to operationally useless prose