diataxis-tutorial

Produces a tutorial in the Diataxis sense: learning-oriented. The reader is a beginner; success is that they finish having done something real and feel capable. A tutorial is not a how-to (task-oriented) and not an explanation (understanding-oriented) — keep those modes out.

Pattern (industry: Diataxis, diataxis.fr)

1. Promise — one sentence: what the learner will have built/done by the end.
2. Prerequisites — the minimum concrete setup, already working.
3. Numbered steps — each step is an action with a visible result the learner can check. Small, ordered, no branching.
4. Checkpoints — after key steps, "you should now see…" so they self-verify.
5. Conclusion — name what they accomplished; point to how-to/reference next.

Rules that keep it a tutorial

• Teach by doing; defer the "why". If background reasoning would help, point to a named Diataxis explanation document — not a reference or how-to — rather than silently deleting the content with no forward pointer.
• One happy path. No options, no alternatives, no decision trees for things that might go wrong mid-lesson.
• Everything must work if followed verbatim: no unfilled placeholders, no deferred setup ("configure as needed").
• Use the imperative ("Run…", "Open…"), present the result every time.

MIF frontmatter

type: procedural (learning by doing). Climb to L2 with namespace, tags, title when known. Gate every output with mif-validate --level 1.

See templates/good.md (a conformant tutorial) and templates/bad.md (a tutorial that has drifted into how-to/reference mixing — the most common error).