Reference template
Use this template for a reference page: factual, look-up content a competent reader scans while working — error codes, rate limits, state tables, field glossaries. This is the Reference quadrant in dev-doc-types. Reference is neutral and complete, not instructional. If you catch yourself writing “first, you will need to…”, that is a how-to — move it out and link to it.When to use
- An error code catalog: “Errors”
- Limits and quotas: “Rate limits”
- A state catalog: “Inbox states”
- A field or term glossary specific to a product area
Always apply
Apply all Foundational skills as you write — writing standards, accessibility, formatting (tables,<ParamField> / <ResponseField>), code examples, terminology. See SKILLS-INDEX.
Template location
assets/template-reference.mdx — structure and placeholders only. Modeled as an errors catalog.Required structure
| Part | Purpose |
|---|---|
| Intro (no heading) | One or two factual sentences. Not a concept explanation. |
| Structured tables | All the data as tables or definition lists — codes, fields, limits, states. |
| Scope note | One line stating what this page does not cover, with a link. |
Writing rules
- Tables over prose for all structured data. A reader scanning for one code should find it without reading sentences.
- Be complete and consistent. Every row carries the same columns. For errors: status code, one-line meaning, retry-safe flag, and a link to the fix.
- No instructional prose. Keep the “how to fix it” in a how-to and link to it — do not embed steps here.
- State the scope. One line on what is out of scope, with a link to where it lives.
- Flag non-standard behavior loudly. If a field, status code, or response shape deviates from the relevant RFC or common convention, call it out explicitly — ideally in the heading (
## Non-standard: ...) — and state what the standard behavior would be. Agents assume the standard unless told otherwise.
Parameter and response-field annotation standard (Gap A)
For any reference page that documents parameters or response fields, every entry must meet this bar — so an agent can use the page as its sole source of truth: Parameter table columns (minimum):| Column | What to show |
|---|---|
| Name | Exact key |
| Type | string, integer, boolean, object, array |
| Required | Yes / No (never omit) |
| Constraints | Min/max, enum values, regex, format — or — if none |
| Default | Explicit value or — |
| Description | One-line: what it controls and why the reader would set it |
inbox.visibility_timeout) or a sub-table. Never write “an object with properties” without listing the properties.
Response-field table columns (minimum):
| Column | What to show |
|---|---|
| Field | Exact key (use dotted notation for nested) |
| Type | As above |
| Description | Meaning + what to do with it — not just what it is |
| Field | Type | Description |
|---|---|---|
inbox_id | string (uuid) | ID of the created inbox. Pass to every subsequent inbox operation. |
status | string (enum) | pending → active → error. Poll until active before sending messages. |
visibility_timeout | integer | Seconds a leased message is hidden from other consumers. Minimum: 1. Maximum: 43200. |
Errors page convention (Stripe pattern)
The errors reference is the factual catalog; the fix is a how-to. They link to each other bi-directionally:- This reference: status code, meaning, retry-safe?, and a link to the matching how-to (error-handling variant).
- The how-to: the diagnostic steps, linking back here.
Naming
- Noun-phrase title and headings: “Errors”, “Rate limits”, “Inbox states”.
- Never a verb phrase — that signals a how-to.
Frontmatter
Set onlytitle and description (see formatting-guidelines).
Before you finish
- Confirm every code, field, and limit against the source OpenAPI spec (code-examples accuracy rules).
- Register the page in
docs.jsonand updatellms.txt(contribute-docs), then run review-before-done.