A recipe solves a goal

For anything composable — search, mutations, scheduling, analytics — recipes are mandatory. Not optional, not nice-to-have.

A real recipe has three parts:

1. A problem statement phrased the way a user would actually ask it
2. The smallest pipeline that solves it
3. The output shape the reader will see

Anything less is filler.

Real vs filler

Real recipe:

Find threads where you're the bottleneck, ranked by overdue:

mxr owed --format json \
  | jq -r 'sort_by(-.overdue_score) | .[0:20] | .[]
           | "\(.overdue_score | tostring | .[0:4])\t\(.counterparty_email)\t\(.subject)"'

Top 20 threads, ranked by waiting_days / expected_days. Same set as mxr search 'is:owed-reply' — pick whichever surface fits your script.

Filler recipe:

mxr owed --format json

Lists owed replies in JSON.

The filler version restates --help. The real one ranks, slices, formats, and tells the reader why the alternative surfaces exist. The reader can paste it and get an answer; the filler one teaches nothing the reference page didn't already say.

What the recipe section is for

A recipe section earns its place by composition. If a tool isn't composable, recipes don't make sense — write reference. If it is composable, the recipes are where readers learn what the composition is good for.

The "What you get" line at the end of each recipe is the critical part. Not "JSON" but "a list of thread IDs with overdue scores." The output shape is what tells the reader whether this is the pipeline they want.

Why filler creeps in

Authors writing recipes without a concrete goal end up restating reference. The trick is to start from a real job, not from a flag. "I want to find X" → pipeline → output. Never "this flag exists, here's how to call it" → that's reference, not a recipe.

See also

• How I Write Software Docs — the full synthesis
• Operationally Useful Docs — the anti-goal recipes are the structural fix for
• Diátaxis Quadrants — recipes live in the how-to quadrant