Diátaxis How-To Quadrant
Parent: Writing and Documentation · researched 2026-05-29T19:02:11.024Z· 5 sources · 10 concepts · skill howto-writing
A how-to guide is a recipe. It serves a competent user who has arrived at the page with a specific goal already formed — "How do I add OAuth to my app?" — and who needs an efficient series of steps to
Overview
- A how-to guide is a recipe. It serves a competent user who has arrived at the page with a specific goal already formed - "How do I add OAuth to my app?" - and who needs an efficient series of steps to get there. [source]
- The single most-violated rule: how-tos answer a question only a competent user could ask. If your reader cannot even formulate the goal, they need a tutorial. [source]
1. Title starts with "How to <verb>"
- "How to rotate the signing key". "How to add a custom domain". If you cannot fit your doc's purpose into that pattern, you do not have a how-to. [source]
2. One goal per document
- A how-to with three goals is three how-tos that have not yet been separated. Each goal gets its own URL, its own title, its own search hit. [source]
3. Prerequisite block up front
- The first block under the title says what the reader must already have, know, or have done. If the reader can't tick every box, they bounce - which is correct, because the doc is not for them yet. [source]
4. Numbered, imperative steps
- Steps are numbered. Each step begins with an imperative verb. "Create…", "Run…", "Set…", "Verify…". Not "Now you might want to…", not "Let's…". [source]
5. Assume competence, omit teaching
- A how-to does not explain what a Kubernetes namespace is. Link out to an explanation or reference doc if useful; do not inline the lesson. [source]
6. Branches are allowed (unlike tutorials)
- How-tos can branch: "If you use Atlas, run X; if you self-host, run Y." Keep branches shallow (1–2 levels) and label them clearly. [source]
7. Verifications, not promises
- Tutorials promise "you'll see exactly this". How-tos verify: "Confirm that kubectl get pods shows the new pod in Running state." [source]
8. Failure modes are part of the recipe
- When a step can plausibly fail, name the failure inline: "If you see Permission denied, your role does not have clusterAdmin - see granting roles." [source]
9. End at the goal, not past it
- When the reader has done the thing, stop. Optional follow-up belongs in a See also block, not in the numbered list. [source]
Template — minimum viable how-to
- <verification command> [source]
AP-1 — Teaching inside the how-to
AP-2 — Multi-goal mega-guide
AP-3 — Tutorial drift
- Narrator voice ("we'll now create…"), promise language ("you'll see exactly…"). Either commit to the tutorial form or trust the reader. [source]
AP-4 — Missing prerequisites
- The reader hits step 3 and discovers they needed kubectl configured. The prerequisite block is the contract. [source]
AP-5 — No verification
- Twelve steps, no checks. Insert verification at every decision point and at the end. [source]
Decision Heuristics
- Could the reader phrase their question as "How do I <verb>?" before reading? If they couldn't even ask, they need a tutorial. [source]
- Is there exactly one goal? If not, split. [source]
- Does the reader already own the vocabulary? If you need to define basic terms, you are drifting into tutorial or explanation. [source]
- Is the goal a daily task, or a once-ever production-critical event? Once-ever production-critical events with rollback procedures are runbooks, not how-tos. [source]
References
Children
- Prerequisite blocks (frontier)
- Imperative steps (frontier)
- Cookbook conventions (frontier)
- Branching guides (frontier)
- How-to vs tutorial (frontier)
Frontier under this node: Branching guides, Cookbook conventions, How-to vs tutorial, Imperative steps, Prerequisite blocks