Diátaxis Reference Quadrant

Reference Doc Writing — Diátaxis Reference Quadrant

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.

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.

Core Concepts

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.

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.

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.

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”.

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.

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.

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).

8. Stable ordering

• Alphabetical for catalogs (CLI flags, config keys, error codes).
• Logical / call-order for function references (constructor, then lifecycle methods, then utility methods).
• Signature-order for parameter tables (positional first in their declared order; keyword/optional after).

Templates

Template — function/method reference

# `<functionName>(<params>) → <return>`

<One-sentence factual statement of what the function does.>

**Since:** v1.4
**Stability:** stable

## Parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `opts.timeout` | `number` (ms) | no | `30000` | Maximum time before the call rejects with `TimeoutError`. Must be ≥ 0. |

## Returns

`Promise<Result>` — resolves with `Result` on success. Rejects with one of the errors below.

## Errors

| Code | Class | Thrown when |
|---|---|---|
| `TIMEOUT` | `TimeoutError` | `opts.timeout` elapsed before the call resolved. |

## Example

```js
const r = await client.fetchThing(id, { timeout: 5000 });

See also

• <relatedFunction> — for the streaming variant.

### Template — CLI flag reference

```markdown
# `mytool deploy`

Deploy the current project to the configured target.

## Synopsis

mytool deploy [–target ] [–dry-run] [–force]

## Flags

| Flag | Type | Default | Description |
|---|---|---|---|
| `--target <name>` | string | `production` | Named target from `config.yaml`. |
| `--dry-run` | bool | `false` | Print planned actions; make no changes. |

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success. |
| 2 | Configuration error. |

Anti-Patterns

AP-1 — Examples that teach instead of describe

“Imagine you have a user signup form. You’d call createUser like this…”

That’s a tutorial example. Strip the narrative.

AP-2 — “Recommended” / “preferred” / “you should”

These are advice. Move them to a how-to.

AP-3 — Missing defaults, units, or nullability

Every parameter without a documented default is a footgun.

AP-4 — Incomplete error tables

“Throws on failure.” — What failures? Under what conditions? With what code?

AP-5 — Mixed ordering

Parameters listed alphabetically on one page, by signature on another. The reader’s skim speed collapses.

Decision Heuristics

1. Will the reader arrive via search, looking for a specific name? If yes → reference.
2. Is the content exhaustive coverage of a surface area? If you can plausibly omit items “for brevity”, you are not writing reference.
3. Is the voice neutral and factual? If you find “you’ll want…” — that’s a how-to hiding inside.

When it’s not reference, switch quadrants:

• Newcomer onboarding → tutorial-writing
• Goal-directed recipe → howto-writing
• Background / why / discussion → explanation-doc-writing
• REST/SDK endpoint authoring → api-docs-craft

References

1. Reference — Diátaxis
2. Reference guides — Divio Documentation