| name | diataxis-how-to |
| description | Write a Diataxis how-to guide — a task-oriented recipe that walks a competent user through accomplishing one real, already-understood goal, start to finish. Use when the user knows what they want to do and needs the steps, not learning or background. Anti-trigger; for a beginner learning by doing use diataxis-tutorial, for looking up facts use diataxis-reference. |
| argument-hint | <the task to accomplish> |
diataxis-how-to
Produces a how-to guide in the Diataxis sense: task-oriented. The reader is
already competent and has a specific goal in mind; success is that the goal is
accomplished. A how-to is not a tutorial (it does not teach) and not reference
(it does not catalog) and not explanation (it does not theorize) — keep those
modes out.
Pattern (industry: Diataxis, diataxis.fr)
- Title — states the goal directly: "How to
accomplish X".
- Context line — one or two sentences naming when/why you'd do this.
- Prerequisites — the concrete starting state and access the task assumes.
- Numbered action steps — an ordered sequence of real commands/actions that
move from the starting state to the goal. Each step does one thing.
- Completion — a short line confirming the goal is now met. Stop there.
Rules that keep it a how-to
- Assume competence. Do not teach concepts or define terms — link out instead.
- No theory, background, or "why it works" prose — that is an explanation doc.
This holds inside a step's own sentence, not just as separate paragraphs or
sections: a trailing clause that justifies why the step is safe or explains
a system's internal mechanics (e.g. "...so both are valid at the same time",
"...so any replica still mid-rollout keeps authenticating") is rationale
riding on the same sentence as a real action — cut it, or move it to the
linked explanation doc. A clause naming the step's own direct, immediate
effect (e.g. "restart the service so it loads the new config") is still
action-scoped and fine; the test is whether the clause explains the reader's
own next observable result, or reaches past it to justify the mechanism.
- Serve the user's one goal; do not document every flag or option — that is
reference. Pick the path that accomplishes the task.
- Real, runnable commands — no
TODO, no <your-value-here> left unexplained.
- End at task completion. No "next you could also…" tours.
Correcting a draft that has drifted into another genre
When the task is to fix an existing how-to (not author from scratch), it will
often contain theory, background, or "why it works" prose that belongs in
explanation, or an exhaustive option catalog that belongs in reference. Do
not delete that content. Deleting it discards knowledge the author put there
for a reason — it just needs a different home. Instead, relocate it:
- Identify a target document for the misplaced content: an existing
explanation/reference doc in the doc set, or — if none exists — a new stub
(e.g.
/explanation/<topic>.md) that captures the removed material.
- Move the theory/background prose (or option catalog) into that target
document, not into a comment or an unreferenced scratch file.
- Add a typed relationship in the corrected how-to's frontmatter pointing at
it —
relationships: [{type: relates-to, target: <path>}] (see the L2
exemplar below) — using an explanation-typed target for theory content,
distinct from the reference-typed target the how-to already carries for its
command catalog.
- Leave one short pointer sentence in the how-to's prose (e.g. "See
<link>
for why this works") so a human reader isn't left wondering where the
context went.
Only when no target can plausibly hold the content (it's genuinely redundant
or wrong) is outright deletion correct — and that should be the exception, not
the default move when cleaning up a draft.
MIF frontmatter
type: procedural (a how-to is a procedure). The genre's MIF ceiling is L2 —
a procedure carries no decision-grade ontology, provenance, or citations the way
an ADR (L3) does, so author to L2 and stop there rather than fabricating L3
fields.
Why machine-readable — the point of MIF here
A how-to's commands rot when the underlying tooling changes; an agent that wants
to reuse or surface one must know whether it is still current and what it pairs
with. As prose (L1) that requires reading and inferring from the steps. The MIF
layer makes those questions answerable by reading frontmatter:
| Question an agent asks | Answered by (frontmatter) |
|---|
| Is this procedure still current? | temporal.ttl / temporal.validFrom |
| When was it last revised? | modified |
| Which reference catalogs its commands? | typed relationships[] (relates-to) |
| Where does it file in the doc set? | namespace + tags |
The same document still reads as a human how-to and projects losslessly to
JSON-LD and back — one artifact, two readers.
The L1 -> L2 climb (two exemplars)
This skill ships the same procedure at both MIF levels so the climb is
explicit:
templates/good-l1.md — L1 floor: id, type, created + body. A valid
how-to, but opaque to a machine consumer. Gate with mif-validate --level 1.templates/good.md — L2 (highest this genre supports): adds namespace,
modified, temporal validity, and a typed relates-to relationship to the
reference doc it pairs with. Gate with mif-validate --level 2.
Author at the highest level the drafting context supports (grade down rather
than fabricate). templates/bad.md shows the antipattern: a how-to that has
drifted into tutorial hand-holding, theory dumps, and exhaustive option catalogs
— the most common error.
