Diátaxis How-To Quadrant
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/howto-writing.md
↓ Facts as markdownall context files
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
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#overview]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#overview]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#1-title-starts-with-how-to-verb]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#2-one-goal-per-document]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#3-prerequisite-block-up-front]
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…". [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#4-numbered-imperative-steps]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#5-assume-competence-omit-teaching]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#6-branches-are-allowed-unlike-tutorials]
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." [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#7-verifications-not-promises]
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." [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#8-failure-modes-are-part-of-the-recipe]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#9-end-at-the-goal-not-past-it]
Template — minimum viable how-to
- <verification command> [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#template-minimum-viable-how-to]
AP-1 — Teaching inside the how-to
- > "Before we deploy, let's understand what a deployment is…" [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-1-teaching-inside-the-how-to]
- The reader knows what a deployment is. If they don't, link an explanation doc. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-1-teaching-inside-the-how-to]
AP-2 — Multi-goal mega-guide
- > "How to configure, deploy, and monitor your service" [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-2-multi-goal-mega-guide]
- That is three guides. Split them. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-3-tutorial-drift]
AP-4 — Missing prerequisites
- The reader hits step 3 and discovers they needed kubectl configured. The prerequisite block is the contract. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-4-missing-prerequisites]
AP-5 — No verification
- Twelve steps, no checks. Insert verification at every decision point and at the end. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#ap-5-no-verification]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#decision-heuristics]
- Is there exactly one goal? If not, split. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#decision-heuristics]
- Does the reader already own the vocabulary? If you need to define basic terms, you are drifting into tutorial or explanation. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#decision-heuristics]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#decision-heuristics]
References
- How-to guides - Diátaxis [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#references]
- Documentation Quadrants - Dunn [archived source: https://llms-explorer.com/sources/mdb-context-hub/howto-writing/#references]
Where this helps
- Writing task-oriented documentation for a user who already knows why they want to do something and just needs the steps, such as "How do I add OAuth to my app?" [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Documenting an operational runbook where steps must be numbered, imperative, and include verification points so an on-call engineer can execute under pressure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Splitting an overloaded "getting started" doc that's secretly trying to be a tutorial, a how-to, and a reference all at once. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing a troubleshooting guide where failure modes at each step need to be documented alongside the happy path. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Title the doc "How to <verb the specific goal>" rather than a vague noun phrase, so a reader can tell from the title alone whether this page solves their problem. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- List prerequisites — versions, permissions, prior setup — up front before step 1, so a reader doesn't discover a missing dependency three steps in. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Write steps as numbered, imperative commands rather than descriptive prose, and end each step, or the guide, with a verification the reader can check. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Stop at the goal — resist the urge to explain why each step works or to cover every possible variation, since that content belongs in an explanation or reference doc instead. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Teaching concepts inside a how-to guide instead of assuming the reader's existing competence, which slows down the exact reader the format is meant to serve. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing a multi-goal mega-guide that tries to cover every related task in one page instead of one goal per document. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Letting a how-to guide drift into tutorial territory with narrator voice and hand-holding instead of direct, imperative steps. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Publishing a how-to guide with no prerequisite block, so readers discover a missing dependency mid-task instead of before starting. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- How-to guides assume reader competence; if the actual audience includes newcomers, a pure how-to will lose them at the first unexplained term or skipped basic step. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Multi-goal "mega-guides" are a persistent temptation because writers want one page to cover everything, but they make the doc harder to search and harder to keep accurate as any one goal's steps change. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Branches — alternate paths for different configurations — are allowed in how-to guides but multiply maintenance burden, since every branch needs testing when the underlying steps change. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A how-to guide with no verification step leaves the reader unsure whether they actually succeeded, especially for tasks with a delayed or non-obvious success signal. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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