Diátaxis Reference Quadrant
Parent: Writing and Documentation · researched 2026-05-29T19:02:13.203Z· 5 sources · 10 concepts · skill reference-doc-writing
Reference documentation is a description. It tells the reader what something is, what its parts are, and what each part does. It does not teach, it does not advocate, and it does not narrate.
Overview
- Reference documentation is a description. It tells the reader what something is, what its parts are, and what each part does. It does not teach, it does not advocate, and it does not narrate. [source]
- The single most-violated rule: reference does not interpret. It states facts. Discussion belongs in explanation docs; storytelling belongs in tutorials; opinions belong nowhere in reference. [source]
1. Architecture mirrors the thing described
- If the product has modules, the reference has modules. If a class has methods, the doc has a section per method. The doc topology is isomorphic to the API topology. [source]
2. Exhaustive coverage beats narrative
- Every parameter is listed. Every return value is documented. Every error code is enumerated. There is no "for brevity we omit…" - reference is the only place where the reader can be sure they have not missed an option. Omissions are bugs. [source]
3. Strict consistency
- Every function reference has the same sections in the same order. Every parameter table has the same columns. Consistency lets a reader who has read one page skim the next page at 10× speed. [source]
4. Neutrality
- Reference does not say "you'll usually want…", "the recommended approach is…". Reference states: "timeout: integer, milliseconds, default 30000, minimum 0, maximum 600000". [source]
5. Examples illustrate, never teach
- Reference examples are specimens, not lessons. A canonical-call example shows the shape - argument positions, return shape, a representative success and a representative failure. [source]
6. The no-surprises rule
- Anything that could surprise a working reader must be stated explicitly: default values, units (ms vs seconds), whether a field is nullable, whether the method mutates input, whether order matters. [source]
7. Search-discoverability
- Reference is read by search, not by table-of-contents traversal. The page title and the first sentence must contain the term the reader will type. Headings must be the names of the things they describe (POST /v1/users, createSession(opts), --max-retries). [source]
8. Stable ordering
- Alphabetical for catalogs (CLI flags, config keys, error codes). [source]
- Logical / call-order for function references (constructor, then lifecycle methods, then utility methods). [source]
- Signature-order for parameter tables (positional first in their declared order; keyword/optional after). [source]
Template — function/method reference
- const r = await client.fetchThing(id, { timeout: 5000 }); [source]
Template — CLI flag reference
- mytool deploy [--target <name>] [--dry-run] [--force] [source]
AP-1 — Examples that teach instead of describe
AP-2 — "Recommended" / "preferred" / "you should"
- These are advice. Move them to a how-to. [source]
AP-3 — Missing defaults, units, or nullability
- Every parameter without a documented default is a footgun. [source]
AP-4 — Incomplete error tables
- > "Throws on failure." - What failures? Under what conditions? With what code? [source]
AP-5 — Mixed ordering
- Parameters listed alphabetically on one page, by signature on another. The reader's skim speed collapses. [source]
Decision Heuristics
- Will the reader arrive via search, looking for a specific name? If yes → reference. [source]
- Is the content exhaustive coverage of a surface area? If you can plausibly omit items "for brevity", you are not writing reference. [source]
- Is the voice neutral and factual? If you find "you'll want…" - that's a how-to hiding inside. [source]
- When it's not reference, switch quadrants: [source]
- Newcomer onboarding → tutorial-writing [source]
- Goal-directed recipe → howto-writing [source]
- Background / why / discussion → explanation-doc-writing [source]
- REST/SDK endpoint authoring → api-docs-craft [source]
References
Children
- Parameter tables (frontier)
- Exhaustive coverage (frontier)
- No-surprises rule (frontier)
- Structure-mirrors-product (frontier)
- Search-discoverability (frontier)
Frontier under this node: Exhaustive coverage, No-surprises rule, Parameter tables, Search-discoverability, Structure-mirrors-product