Skip to content
mif-docs

Skill reference: diataxis-explanation

Skill reference: diataxis-explanation

Section titled “Skill reference: diataxis-explanation”

The diataxis-explanation skill authors one document genre: a Diátaxis explanation — an understanding-oriented discussion of the why behind a topic. 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
AuthorsAn understanding-oriented explanation
Purpose groupDiátaxis quadrants
MIF conceptTypesemantic
Target MIF level3
Primary sourceDiátaxis — Explanation

What this document type is

Section titled “What this document type is”

An explanation is one of the four Diátaxis modes. Its defining property is that it is understanding-oriented: it exists to illuminate a topic — to give background, rationale, design history, trade-offs, and the connections between one idea and others — so the reader comes away understanding why things are the way they are. Diátaxis describes explanation as discursive and reflective: it is read away from the work, at leisure, to deepen and broaden comprehension rather than to perform an immediate task. It admits opinion and alternative views; it can discuss what might have been and why it was not.

An explanation is therefore not a tutorial (which teaches a beginner by doing), not a how-to guide (which drives a competent user to a goal), and not reference (which states facts neutrally for lookup). Explanation is the one mode defined by its relationship to understanding rather than to action or information, and folding it into the action-oriented genres — pausing a tutorial or how-to to philosophize — is a classic Diátaxis failure the separation exists to prevent.

How the skill produces one

Section titled “How the skill produces one”

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

  • Pattern, made operational. The skill encodes the understanding-oriented constraints — discuss the why, supply context and rationale, draw connections and weigh trade-offs, stay clear of step-by-step instruction — and refuses anti-triggered work (a known task belongs in a how-to; a fact 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 3 for an explanation), 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 explanation is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic, reflecting that it conveys understanding and relationships rather than a sequence of 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-explanation when the reader needs to grasp a concept or a decision: why an architecture is shaped as it is, what trade-offs a design accepted, how one idea relates to another. Good explanation is what lets a reader reason about a system instead of merely operating it, and it is the natural home for the rationale that would otherwise clutter the action-oriented genres.

Do not use it when the reader wants to do something — a task they understand wants a how-to guide; a beginner wants a tutorial — or when they want a bare fact, which belongs in reference. The trade-off is that explanation does not directly advance a task: it is read at leisure for comprehension, so its value is real but diffuse, and over-investing in it before the action genres exist can leave users understanding a system they still cannot use.

Example

Section titled “Example”

An explanation titled “Why MIF uses lossless Markdown ↔ JSON-LD round-trips” discusses the design problem — keeping one artifact legible to humans and parseable by machines — sketches the alternatives that were rejected, names the trade-offs the round-trip constraint accepts, and connects the choice to provenance and the MIF level model. It gives the reader no steps to follow and no field table to scan; it leaves them understanding the rationale. The suite’s own explanation material is written to this shape.

Provenance & citations

Section titled “Provenance & citations”