Diátaxis Tutorial Quadrant
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/tutorial-writing.md
↓ Facts as markdownall context files
A tutorial is a lesson. Its only job is to take a complete newcomer through a meaningful, hand-held experience and leave them with two things: a tiny working artifact they built themselves, and the co
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 tutorial is a lesson. Its only job is to take a complete newcomer through a meaningful, hand-held experience and leave them with two things: a tiny working artifact they built themselves, and the confidence that they can use this tool. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#overview]
- The single most-violated rule: the artifact does not matter; the learning does. A tutorial reader is not there to ship the thing they build - they are there to encounter the tool, the vocabulary, and the shape of the workflow under your protection. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#overview]
- If you find yourself optimizing for "they could use this output in production" - stop. You are writing a how-to. Switch quadrants. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#overview]
1. The learner's promise
- When a learner runs your step, they must see the result you said they would see. This is non-negotiable. Confidence is built layer by layer, and one broken step shakes the whole stack. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#1-the-learners-promise]
- Re-test every step on a clean environment before you ship. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#1-the-learners-promise]
2. Narrator voice — "we" not "you alone"
- Tutorials use the first-person plural: "we'll create a file called app.py", "now we'll run it". The instructor is present. The learner is not abandoned. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#2-narrator-voice-we-not-you-alone]
- Contrast with how-to voice ("Create a file named app.py") which assumes competence. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#2-narrator-voice-we-not-you-alone]
3. No detours
- There will be a hundred interesting tangents - "by the way, you could also…", "in production you'd usually…". Cut all of them. Every sentence either moves the learner toward the artifact or it leaves the document. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#3-no-detours]
4. Exit-with-a-completed-artifact
- The learner must finish with something visible: a running web server on localhost:8000, a printed "Hello, world", a deployed function that responded to a curl. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#4-exit-with-a-completed-artifact]
5. Cognitive load budget (7±2)
- Human working memory holds roughly 7 ± 2 items. Each step introduces one new thing. Earlier-introduced things are reused, not re-explained. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#5-cognitive-load-budget-72]
6. Backward design (Carpentries)
- Start at the end. Write down - in one sentence - what the learner can do after the tutorial that they could not do before. Then work backwards. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#6-backward-design-carpentries]
7. Concrete, particular, robust
- Tutorials are built around specific actions and specific outcomes. Not "create a database" - "create a database called tutorial_db". Not "you'll see some output" - "you'll see exactly this output: {...}". [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#7-concrete-particular-robust]
8. The instructor's safety contract
- The reader is a guest in your kitchen; you don't let them touch the hot pan. If the install command on macOS 14 prompts for a password and the learner does not expect it, that is your error, not theirs. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#8-the-instructors-safety-contract]
9. Inspire confidence, not competence
- The goal is "I can do this", not "I have mastered this". [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#9-inspire-confidence-not-competence]
10. Tutorials are not the place for "if" or "depending on"
- Branching kills tutorials. Pick one environment, declare it in step 0, and keep one linear path. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#10-tutorials-are-not-the-place-for-if-or-depending-on]
Template — minimum viable tutorial
- <exact expected output> [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#template-minimum-viable-tutorial]
AP-1 — The "tutorial" that is secretly reference
- > "This tutorial covers the Client class, which has the following methods…" Tutorials walk a learner through doing one thing; they do not enumerate surface area. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-1-the-tutorial-that-is-secretly-reference]
AP-2 — The "kitchen sink" tutorial
- Twelve features, three languages, two installation paths. Pick one concrete artifact, one environment, one path. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-2-the-kitchen-sink-tutorial]
AP-3 — Theory before action
- Three paragraphs of background before the first command. Get them to Hello, world in the first five minutes. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-3-theory-before-action]
AP-4 — Hand-waved steps
- "Now set up your database." How? Which database? On what port? Every imperative must be copy-pasteable. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-4-hand-waved-steps]
AP-5 — Untested steps
- Tutorials decay. Re-run the entire tutorial on a clean VM before each release. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-5-untested-steps]
AP-6 — "You'll see something like…"
- Either it's exact or you've broken the learner's promise. Show the exact output. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#ap-6-youll-see-something-like]
Decision Heuristics
- Is the reader a complete newcomer? If they could already articulate a specific goal, they need a how-to. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- Is the artifact small enough that you can guarantee every step? If not, split it. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- Is there exactly one path through? If you find "if/depending on/optionally", you are drifting toward how-to. [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- Does the reader end with a visible, working thing they built themselves? [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- Competent reader with a goal → howto-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- "Why does this exist?" → explanation-doc-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
- "What are the parameters of foo()" → reference-doc-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics]
References
- Tutorials - Diátaxis [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#references]
- Collaborative Lesson Development Training - Lesson Design (The Carpentries) [archived source: https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#references]
Where this helps
- Onboarding a complete newcomer to a tool or codebase who needs a hand-held, guaranteed-to-work first experience rather than a menu of options. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing a "getting started" doc where the goal is building the reader's confidence that they can succeed with this tool, not teaching them everything about it. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Designing a workshop or training exercise where cognitive load must stay within the learner's working-memory budget, roughly 7±2 new concepts. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding that an existing "tutorial" is actually a disguised reference doc, covering every option and configuration, and needs to be split so newcomers aren't overwhelmed. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Write in narrator voice — "we" — rather than commanding the reader alone, so the tutorial reads as a guided experience rather than an exam. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Design backward from the finished artifact the learner will have built, then choose only the steps that lead there in a straight line, per the Carpentries' backward-design approach. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Cut every "if you're using X instead" branch or "depending on your setup" caveat — tutorials should follow one exact, tested path, leaving alternatives for a how-to guide. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Budget cognitive load deliberately: introduce roughly 7±2 new concepts at most before the learner reaches a working checkpoint, not a wall of new ideas before anything runs. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Writing a "tutorial" that's secretly a reference doc, covering every configuration option instead of one guaranteed, hand-held path. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Building a "kitchen sink" tutorial that tries to showcase every feature instead of the minimum path to one working artifact. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Front-loading theory before the learner has done anything, instead of getting them to a working checkpoint first and explaining afterward. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Publishing untested steps, or writing "you'll see something like…", which signals the exact path was never actually verified end to end. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Tutorials require the most testing discipline of the four quadrants — untested steps that fail on a real learner's machine break trust immediately and are the single most common tutorial failure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The no-detours rule is hard to hold under pressure to be comprehensive; authors keep wanting to explain why a step works, which pulls the tutorial toward becoming an explanation doc mid-stream. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- A tutorial's promise — a working artifact by the end — can silently break as the underlying tool changes versions, since tutorials are rarely re-tested as often as reference docs are updated. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Phrases like "you'll see something like…" signal an untested or environment-dependent step, and they undermine the tutorial's core promise that following the exact steps produces the exact result. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Children
- Backward design (frontier)
- Cognitive load 7±2 (frontier)
- Narrator voice (frontier)
- Learner's promise (frontier)
- Carpentries pedagogy (frontier)
Frontier under this node: Backward design, Carpentries pedagogy, Cognitive load 7±2, Learner's promise, Narrator voice