Diátaxis Reference Quadrant
Parent: Writing and Documentation · Published reference · snapshot 2026-09-08 · skill technical-writing-craft/references/reference-doc-writing.md
↓ Facts as markdownall context files
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.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#overview]
- 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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#overview]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#1-architecture-mirrors-the-thing-described]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#2-exhaustive-coverage-beats-narrative]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#3-strict-consistency]
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". [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#4-neutrality]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#5-examples-illustrate-never-teach]
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. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#6-the-no-surprises-rule]
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). [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#7-search-discoverability]
8. Stable ordering
- Alphabetical for catalogs (CLI flags, config keys, error codes). [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#8-stable-ordering]
- Logical / call-order for function references (constructor, then lifecycle methods, then utility methods). [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#8-stable-ordering]
- Signature-order for parameter tables (positional first in their declared order; keyword/optional after). [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#8-stable-ordering]
Template — function/method reference
- const r = await client.fetchThing(id, { timeout: 5000 }); [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#template-functionmethod-reference]
Template — CLI flag reference
- mytool deploy [--target <name>] [--dry-run] [--force] [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#template-cli-flag-reference]
AP-1 — Examples that teach instead of describe
- > "Imagine you have a user signup form. You'd call createUser like this…" [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-1-examples-that-teach-instead-of-describe]
- That's a tutorial example. Strip the narrative. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-1-examples-that-teach-instead-of-describe]
AP-2 — "Recommended" / "preferred" / "you should"
- These are advice. Move them to a how-to. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-2-recommended-preferred-you-should]
AP-3 — Missing defaults, units, or nullability
- Every parameter without a documented default is a footgun. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-3-missing-defaults-units-or-nullability]
AP-4 — Incomplete error tables
- > "Throws on failure." - What failures? Under what conditions? With what code? [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-4-incomplete-error-tables]
AP-5 — Mixed ordering
- Parameters listed alphabetically on one page, by signature on another. The reader's skim speed collapses. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#ap-5-mixed-ordering]
Decision Heuristics
- Will the reader arrive via search, looking for a specific name? If yes → reference. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- Is the content exhaustive coverage of a surface area? If you can plausibly omit items "for brevity", you are not writing reference. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- Is the voice neutral and factual? If you find "you'll want…" - that's a how-to hiding inside. [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- Newcomer onboarding → tutorial-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- Goal-directed recipe → howto-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- Background / why / discussion → explanation-doc-writing [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
- REST/SDK endpoint authoring → api-docs-craft [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#decision-heuristics]
References
- Reference - Diátaxis [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#references]
- Reference guides - Divio Documentation [archived source: https://llms-explorer.com/sources/mdb-context-hub/reference-doc-writing/#references]
Where this helps
- Documenting an API's function signatures, parameters, and return types where the reader needs an exhaustive, look-up-able description, not a narrative. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Writing a CLI flag reference where every flag needs consistent formatting — default value, type, whether required — so users can scan rather than read start to finish. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Auditing an existing reference doc for the no-surprises rule, checking that its structure mirrors the actual code or API structure so readers can predict where to find something. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Deciding that a reference page's examples have started teaching concepts rather than just illustrating usage, and need to be trimmed back or moved to a how-to or tutorial. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
How to apply this
- Mirror the reference doc's structure to the structure of the thing it describes — module to class to method, or command to subcommand to flag — so navigation is predictable. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Cover every parameter, default, unit, and nullability explicitly rather than only the common cases, since omissions in reference docs get discovered the hard way by users. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Keep examples strictly illustrative — each example should show usage, not teach a concept or advocate a "recommended" approach, which belongs in an explanation or how-to doc. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Maintain strict, consistent ordering — alphabetical, or matching source-code order — across every reference entry so a reader who's used one page already knows where to look on another. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Antipatterns
- Writing examples that teach a concept instead of simply describing usage, which blurs the line between reference and tutorial content. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Slipping "recommended" or "preferred" language into an entry, which breaks the neutrality a reference doc is supposed to maintain. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Leaving out defaults, units, or nullability for a parameter, forcing the reader to discover the missing detail by trial and error. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Documenting error codes inconsistently or incompletely, so the happy path is well covered but failure modes are not. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
Known issues
- Reference docs are exhaustive by design, which makes them tedious to keep accurate — every API surface change requires a corresponding reference update or the doc silently goes stale. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- The neutrality rule (no "recommended" language) is easy to violate unintentionally, especially when an author has a strong preference among several valid options. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Search-discoverability depends on consistent terminology matching what users actually search for, which reference authors don't always test against real user query language. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
- Incomplete error tables are a common, hard-to-notice gap — documenting the happy-path return value is easy, documenting every error code and when it's thrown is much more work and gets skipped under deadline pressure. [source] — AI-suggested, synthesized from this pack's existing facts — not extracted from a source document.
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