documentation-standards

Documentation Standards Reference

> **Scope**: Style guide rules, parameter table quality, heading structure, and prose standards for API and technical documentation. Does NOT cover code example verification (see `api-doc-verification-failures.md`). > **Version range**: Google Developer Documentation Style Guide (current), OpenAPI 3.x > **Generated**: 2026-04-15 — verify against Google style guide current release

---

Overview

Technical documentation accuracy depends on two orthogonal concerns: structural correctness (tables well-formed, headings consistent, links working) and semantic correctness (params match source, types verified, examples tested). This file covers structural standards. The most common failure mode is documenting the wrong thing correctly — a perfectly formatted table describing a parameter that doesn't exist.

---

Pattern Table

| Pattern | Standard | Use When | Avoid When | |---------|----------|----------|------------| | Parameter tables | Google style: Type, Required, Description cols | All endpoint params | Fewer than 2 params (use inline) | | Heading hierarchy | H2 for top sections, H3 for endpoints, H4 for sub-sections | All long docs | Jumping from H2 to H4 | | Code blocks with language tag | ` ```bash `, ` ```json `, ` ```yaml ` | All code samples | Short inline values (use backticks) | | Admonition for warnings | `> **Note:**` or `> **Warning:**` | Destructive ops, gotchas | Every paragraph | | Versioning notes | `**Changed in v2.0:**` prefix | Breaking API changes | Minor doc updates |

---

Correct Patterns

Parameter Tables — Required Column Order

Google style requires Type before Description. Putting Description before Type is the most common table error.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name      | string | Yes    | Resource name (3-63 chars, alphanumeric + hyphens) |
| timeout   | integer | No   | Request timeout in seconds. Default: 30. Range: 1-300 |
| tags      | array of strings | No | Labels for filtering. Max 10 items |

**Why**: Google Developer Style Guide §parameter-tables — Type comes second so readers can scan the type column without reading Description. "Required" as a boolean column (not embedded in Description) enables table sorting in rendered docs.

---

Error Response Tables — Code, Cause, Resolution

Every endpoint needs an error table. "Returns 400 if invalid" is not documentation.

| Code | Cause | Resolution |
|------|-------|------------|
| 400  | `name` is missing or empty | Include `name` field in request body |
| 400  | `name` exceeds 63 characters | Use a name with 3-63 alphanumeric chars or hyphens |
| 401  | Missing `Authorization` header | Add `Authorization: Bearer <token>` header |
| 403  | Token lacks `write` scope | Request a token with the `write` scope from auth service |
| 409  | Resource with this `name` already exists | Choose a unique name or use PUT to update |
| 429  | Rate limit exceeded (100 req/min) | Wait 60 seconds or implement exponential backoff |
| 500  | Internal error | Retry with exponential backoff; contact support with `X-Request-ID` |

**Why**: Each row answers "what do I DO when this happens?" — not just what went wrong. Resolution must be actionable.

---

Authentication Section Placement

Authentication must appear before parameters, not after examples. Readers need auth context before attempting to construct a request.

### POST /api/v1/resources

Creates a new resource.

**Authentication:** Bearer token with `resources:write` scope required.

**Request Parameters:**
...

**Request Example:**
...

**Why**: If auth is after the example, readers copy the example, hit 401, and then hunt for the auth section. Front-loaded auth reduces time-to-first-success.

---

Endpoint Description — 30-Word Limit

Each endpoint description must be one sentence under 30 words.

<!-- Good: 11 words, tells you what the endpoint does -->
Creates a new resource in the specified workspace.

<!-- Bad: 35 words, describes the implementation not the interface -->
This endpoint processes the incoming request data, validates the fields against the schema,
and if all validations pass, creates a new resource entry in the database.

**Why**: Google style §method-descriptions — description is the *interface*, not the implementation. The implementation details belong in architecture docs, not API reference.

---

Pattern Catalog

<!-- no-pair-required: section header with no content -->

Write Specific Parameter Descriptions

**Detection**:

grep -n "the [a-z]* to\|value of\|represents the\|specifies the" docs/**/*.md
rg "the \w+ to use|value of the|this is the" --glob "*.md"

**Signal**:

| config | object | No | The config object to use |
| data   | string | No | The data value |

**Why this matters**: "The config object to use" tells the reader nothing they couldn't infer from the parameter name. It's word-count theater. Readers need to know: what keys does `config` contain? What is the valid range for `data`?

**Preferred action:** Write parameter descriptions that answer what the value means and what constraints apply. Include: the valid range or set of values, the unit (seconds, bytes, count), the effect of omitting an optional field, and any related parameters.

**Preferred action**:

| config | object | No | Configuration overrides. Keys: `timeout` (int, seconds), `retries` (int, 0-5) |
| data   | string | No | Base64-encoded payload. Max 1MB after encoding |

---

Include Required Column in Parameter Tables

**Detection**:

grep -n "| Parameter | Type | Description |" docs/**/*.md
rg "\| Parameter \| Type \| Description \|" --glob "*.md"

**Signal**:

| Parameter | Type | Description |
|-----------|------|-------------|
| name      | string | Resource name |
| config    | object | Configura