The accepted answer on Stack Overflow gets 10x the upvotes of the most-thorough answer. The thorough answer explains the underlying mechanism, walks through three approaches, discusses tradeoffs. The accepted answer is six lines of code that you copy, paste, and ship.

This isn't a sad commentary on shallow learning. It's a structural observation about how developers actually consume documentation. When something is on fire, you want a snippet. Education comes after.

Internal team docs almost universally optimize for the wrong shape. They explain the why (good) but bury the what in prose (bad). Then everyone Slack-messages each other for the snippet anyway, and the doc gets read once during onboarding and never again.

The fix is a documentation format optimized for the actual access pattern: snippets first, explanation later, runnable verbatim.

The format

Each runbook entry has three parts in this order:

## How to clear the Redis cache for one tenant

### The command
docker exec redis-prod redis-cli -n 2 KEYS "tenant:42:*" | \
  xargs docker exec redis-prod redis-cli -n 2 DEL

### Why this works
The tenant data is in DB 2, prefixed with tenant:<id>:. KEYS is fine
here because we expect at most ~10K keys per tenant; for larger sets,
use SCAN.

### When NOT to use this
- During cache warm. Use the tenant-isolated invalidation API.
- Across multiple tenants. Iterate the API, don't batch via redis-cli.

The runnable command comes first. Always. Variables that need replacing are the most obvious thing in the snippet (tenant:42:* is clearly meant to be edited).

Why this beats the prose-first format

Prose-first:

To clear the Redis cache for a specific tenant, you'll need to connect to the Redis container, navigate to the appropriate database (DB 2 for tenant data), and use the KEYS command with the tenant prefix to identify keys, then DEL to remove them. Be aware that KEYS is O(n) in production-scale Redis instances...

A reader at 2 AM bounces off paragraph one. They open another tab, search for "redis clear keys by prefix", land on Stack Overflow, get a snippet, run it. The internal doc you spent 90 minutes writing didn't get used.

Snippet-first inverts the cost: the reader gets the snippet in 5 seconds, runs it, and (this is the magic part) the explanation is right there if they want it after. The reader chooses how deep to go.

What makes a snippet "copy-paste safe"

Three rules:

1. Variables are obvious. Use placeholder names that scream "replace me": <tenant-id>, ${POD_NAME}, your-bucket-name. Not subtle defaults like 42 that someone might leave in production.

2. Side effects are visible. If the command modifies state, lead with --dry-run or -n (no-op) version when the tool supports it:

# Dry-run first
gh pr list --search 'is:open author:bot label:stale' --json number,title

# Then close them
gh pr list --search 'is:open author:bot label:stale' --json number \
  | jq -r '.[].number' | xargs -I{} gh pr close {}

3. Output is verifiable. Include what success looks like:

$ kubectl rollout status deployment/api
Waiting for deployment "api" rollout to finish: 2 of 4 updated replicas...
deployment "api" successfully rolled out

A reader knows immediately if they're seeing the expected output.

What to avoid

Three patterns that turn a good runbook into a bad one:

Multi-step shell pipelines without intermediate verification. Each step should be a separate command the reader can verify before continuing.
"Customize as needed for your environment". The runbook reader is panicking — they don't have time to figure out what to customize. List the specific variables explicitly.
Snippets without context. Each snippet should have one sentence above it stating what it does. Not three paragraphs — one sentence.

The AI-coding-agent angle

This is where the snippet-first format gets a second use case. AI agents — Claude Code, Codex, Cursor's chat — perform dramatically better when given snippet-first runbooks as context vs prose-first ones. The reason is the same as for human readers: the agent extracts the runnable pattern faster, and the explanation/constraint context is positioned where the agent uses it (next to the command, not above the fold).

If you're maintaining internal docs that an AI agent will reference, snippet-first isn't optional anymore. It's the format that makes the agent useful. Prose-first docs cause the agent to generate generic StackOverflow-grade suggestions instead of using your specific runbook.

Migrating an existing doc

You don't have to rewrite everything. Pick the doc your team actually opens (use search analytics if available, or just ask). Restructure that one. Compare engagement before/after.

The migration pattern:

Identify the runnable command at the heart of the doc
Extract it to the top with no prose
Move the prose down into "Why this works" / "When NOT to use this"
Add the expected output below the command

Twenty minutes per doc. The behavior change shows up immediately — people start linking to the doc in chat instead of just typing the snippet directly.

Where this fits in the broader picture

Snippet-first runbooks are a specific case of the principle: documentation should match the reader's access pattern. Tutorials match new-learner pattern. Reference docs match "what's the parameter signature" pattern. Runbooks match "production is on fire" pattern. They're different access patterns and they need different formats.

Most teams write only one type of documentation (whichever format their style guide prefers) and try to make it serve all access patterns. It serves none of them well. Treating runbooks as their own format with their own rules — copy-paste first, snippet visible, explanation deferred — is what makes the runbook actually get used.

The Stack Overflow accepted-answer template won this argument fifteen years ago. Internal documentation just hasn't caught up.