Skip to content
mif-docs

Skill reference: diataxis-reference

Skill reference: diataxis-reference

Section titled “Skill reference: diataxis-reference”

The diataxis-reference skill authors one document genre: a Diátaxis reference — a dry, information-oriented, exhaustive description of one thing. 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 dry, information-oriented reference
Purpose groupDiátaxis quadrants
MIF conceptTypesemantic
Target MIF level3
Primary sourceDiátaxis — Reference

What this document type is

Section titled “What this document type is”

A reference is one of the four Diátaxis modes. Its defining property is that it is information-oriented: it exists to describe one thing — a CLI command, a config file, an API endpoint, a schema — accurately, completely, and neutrally, so a working practitioner can consult it. Diátaxis is emphatic that reference is austere by design: it states what is, without instruction, persuasion, or speculation. Its structure should mirror the structure of the thing it documents — if the machinery has parts, the reference is organized by those parts — so a reader can navigate to a fact the way they would navigate the product itself.

A reference is therefore not a tutorial (which teaches a beginner), not a how-to guide (which drives a competent user to a goal), and not explanation (which discusses the why). Reference is consulted, not read through; a reader arrives knowing what they are looking for and leaves the moment they have it. Smuggling tutorial hand-holding or explanatory argument into reference is the failure Diátaxis warns against — it inflates the material the reader must skim.

How the skill produces one

Section titled “How the skill produces one”

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

  • Pattern, made operational. The skill encodes the information-oriented constraints — describe one thing exhaustively, mirror its structure, stay neutral and dry, omit teaching and rationale — and refuses anti-triggered work (learning belongs in a tutorial; accomplishing a goal belongs in a how-to).
  • 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 a reference), 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 reference is authored with MIF frontmatter (via the shared mif-frontmatter substrate) and a conceptType of semantic, reflecting that reference describes a thing’s properties 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-reference when the reader needs a fact about a specific thing they will consult repeatedly: the flags of a command, the fields of a schema, the parameters of an endpoint. Good reference is the backbone of mature documentation because it is the place practitioners return to, and its neutrality makes it cheap to trust and to keep authoritative.

Do not use it for a reader who is learning — that wants a tutorial — or for someone trying to accomplish a task, which wants a how-to guide. Do not use it to argue or contextualize; the why belongs in explanation. The trade-off is breadth over flow: reference must be exhaustive and is consulted in fragments, so it reads poorly start to finish — that is correct, not a defect.

Example

Section titled “Example”

A reference titled “MIF frontmatter fields” is organized to mirror the schema it documents: one section per top-level key, each stating the field name, its type, whether it is required at L1/L2/L3, and its meaning, in a flat table the reader can scan. It does not narrate how to author a document or argue why the levels exist; it states what each field is and stops. The suite’s own reference material is built to this shape.

Provenance & citations

Section titled “Provenance & citations”