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)

1. Title — states the goal directly: "How to accomplish X".
2. Context line — one or two sentences naming when/why you'd do this.
3. Prerequisites — the concrete starting state and access the task assumes.
4. Numbered action steps — an ordered sequence of real commands/actions that move from the starting state to the goal. Each step does one thing.
5. 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:

1. 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.
2. Move the theory/background prose (or option catalog) into that target document, not into a comment or an unreferenced scratch file.
3. 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.
4. 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:

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.