# Diátaxis Tutorial Quadrant > 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 Parent: [Writing and Documentation](https://llms-explorer.com/tree/writing-and-documentation/) · 24 facets · 48 facts · page: https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/ ## 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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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: {...}". — [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. — [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". — [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. — [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 - — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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. — [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? — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics) - When the answer points elsewhere: — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics) - Competent reader with a goal → howto-writing — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics) - "Why does this exist?" → explanation-doc-writing — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics) - "What are the parameters of foo()" → reference-doc-writing — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#decision-heuristics) ## References - Tutorials - Diátaxis — [source](https://llms-explorer.com/sources/mdb-context-hub/tutorial-writing/#references) - Collaborative Lesson Development Training - Lesson Design (The Carpentries) — [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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(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](https://llms-explorer.com/tree/di-taxis-tutorial-quadrant/) *(AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.)* ## Context files - [Diátaxis Tutorial Quadrant](https://llms-explorer.com/downloads/sources/mdb-context-hub/tutorial-writing.md)