Skip to content
mif-docs

Skill reference: diataxis-how-to

Skill reference: diataxis-how-to

Section titled “Skill reference: diataxis-how-to”

The diataxis-how-to skill authors one document genre: a Diátaxis how-to guide — a task-oriented recipe that walks a competent user through one real goal. 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 task-oriented how-to guide
Purpose groupDiátaxis quadrants
MIF conceptTypeprocedural
Target MIF level2
Primary sourceDiátaxis — How-to guides

What this document type is

Section titled “What this document type is”

A how-to guide is one of the four Diátaxis modes. Its defining property is that it is task-oriented: it serves a user who already knows what they want to accomplish and needs the sequence of actions that gets them there. Diátaxis frames the how-to as a recipe — a set of directions for solving one real-world problem, addressed to someone competent who can adapt the steps to their own situation. It assumes prior knowledge, omits teaching, and is measured by whether the reader reaches the goal, not by what they learned along the way.

A how-to guide is therefore not a tutorial (which teaches a beginner through a crafted first success), not reference (which is consulted for facts, not read through), and not explanation (which discusses the why). The how-to occupies the action quadrant for users who are already capable; mixing in teaching or background dilutes the very leanness that makes it useful.

How the skill produces one

Section titled “How the skill produces one”

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

  • Pattern, made operational. The skill encodes the task-oriented constraints — start from a real goal, give a coherent sequence of actions, address a competent reader, omit explanation — and refuses anti-triggered work (a beginner who needs to learn belongs in a tutorial; a fact lookup belongs 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 how-to), 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 guide is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of procedural, reflecting that a how-to is a sequence of performed actions. 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-how-to when the reader is already competent and has a goal in hand: configuring a feature, integrating two tools, performing an operation they understand but have not memorized. A good how-to is lean — it respects the reader’s time by giving exactly the steps and trusting them to adapt.

Do not use it when the reader is new and needs to learn — that wants a tutorial, which manufactures an early success and carries the learner. Do not use it for lookup material (that is reference) or for background and rationale (that is explanation). The trade-off is that a how-to deliberately withholds teaching: a reader who lacks the assumed competence will be lost, so pitch it to someone who can already operate in the domain.

Example

Section titled “Example”

A how-to titled “Add MIF frontmatter to an existing document” opens by naming the goal in one line, lists what the reader must already have, then gives a tight sequence of actions — open the file, paste the L1 block, fill id and title, run mif-validate, fix any failure — and stops the moment the goal is met. It does not explain what JSON-LD is or why the floor matters; it links those to explanation and keeps the competent reader moving. The suite’s own how-to guides follow exactly this shape.

Provenance & citations

Section titled “Provenance & citations”