Skip to content
mif-docs

Skill reference: diataxis-tutorial

Skill reference: diataxis-tutorial

Section titled “Skill reference: diataxis-tutorial”

The diataxis-tutorial skill authors one document genre: a Diátaxis tutorial — a learning-oriented, hands-on lesson. This reference describes what that document type is, how the skill produces one, when it earns its place, and the provenance and sources behind it.

PropertyValue
AuthorsA learning-oriented, hands-on tutorial
Purpose groupDiátaxis quadrants
MIF conceptTypeprocedural
Target MIF level2
Primary sourceDiátaxis — Tutorials

What this document type is

Section titled “What this document type is”

A tutorial is one of the four Diátaxis modes. Its defining property is that it is learning-oriented: it exists to take a beginner, by the hand, through a single concrete success by doing, so they come away with confidence and a working mental foothold — not a comprehensive understanding and not a finished production task. Diátaxis is explicit that the tutorial’s author is a teacher responsible for the learner’s journey: every step must work, every instruction must be one the learner can follow without prior knowledge, and the lesson must deliver a visible, early, and repeated sense of achievement.

A tutorial is therefore not a how-to guide (which serves a competent user with a goal they already understand), not reference (which is consulted, not read through), and not explanation (which discusses the why). Mixing those modes into a tutorial is the single most common documentation failure Diátaxis names, and the genre exists precisely to keep them separate.

How the skill produces one

Section titled “How the skill produces one”

diataxis-tutorial is a genre skill: it carries the Diátaxis tutorial pattern as durable instructions plus exemplars, and writes the artifact over a MIF floor so the result is at once a human-readable lesson and a machine-conformant unit.

  • Pattern, made operational. The skill encodes the learning-oriented constraints — concrete first success, no digressions into explanation, every step verified — and refuses anti-triggered work (a known task belongs in a how-to; facts belong in reference).
  • Exemplars set the bar. Like every genre in the suite it ships good-l1.md (the MIF Level-1 floor), good.md (the target level — Level 2 for a tutorial), bad.md (a counter-example), and evals/evals.json. The check-exemplars gate proves good-l1.md validates at L1 and good.md at its target level, so the pattern the skill teaches is itself continuously verified.
  • MIF projection. The tutorial is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of procedural, reflecting that a tutorial is a sequence of performed steps. mif-validate proves the Markdown ↔ JSON-LD round-trip is lossless before the document is considered done.

When it is beneficial

Section titled “When it is beneficial”

Reach for diataxis-tutorial when the reader is new and the goal is their confidence: onboarding, getting-started lessons, a first end-to-end walkthrough of a tool or workflow. A good tutorial dramatically lowers the activation energy for adoption because it manufactures an early success the learner can build on.

Do not use it when the reader already knows what they want to accomplish — a task they understand wants a how-to guide, which is leaner and assumes competence. Do not use it for lookup material (that is reference) or for background and rationale (that is explanation). The cost of a tutorial is maintenance: because every step must work, tutorials are the most expensive genre to keep current, so write one where onboarding value justifies that upkeep.

Example

Section titled “Example”

A tutorial titled “Author and validate your first MIF document” opens with a one-sentence promise of what the learner will have built by the end, lists the prerequisites, then walks through numbered steps — create the file, add the L1 frontmatter, run mif-validate, see it pass — each producing a visible result. It does not pause to explain why JSON-LD round-trips; it links that to an explanation and keeps the learner moving toward the success. The suite’s own getting-started tutorial is exactly this shape.

Provenance & citations

Section titled “Provenance & citations”