Reference Documentation

Reference Documentation

Create exhaustive, searchable, and precisely organized technical reference documentation that serves as the definitive source of truth for APIs, configurations, and system interfaces.

When to Use This Skill

• Building API reference documentation (REST, GraphQL, gRPC)
• Creating configuration guides with every parameter documented
• Writing schema documentation for databases or data models
• Producing CLI reference with all commands, flags, and examples
• Generating complete technical specifications
• Documenting error codes, status codes, and exception catalogs
• Creating migration guides for version upgrades

Quick Reference

---

Workflow Overview

Phase 1: Inventory    → Catalog all public interfaces, parameters, and constraints
Phase 2: Author       → Draft structured entries with examples and cross-links
Phase 3: Verify       → Validate against implementation and tests
Phase 4: Organize     → Structure for optimal retrieval and searchability
Phase 5: Maintain     → Version tracking, deprecation, and update cadence

---

Phase 1: Inventory

Enumerate everything that needs documentation before writing anything.

Inventory Checklist

• [ ] All public API endpoints / methods / functions
• [ ] All configuration parameters and their defaults
• [ ] All error codes and exception types
• [ ] All environment variables
• [ ] All CLI commands and flags
• [ ] All schema fields and constraints
• [ ] All event types and payloads
• [ ] Deprecation timeline for removed features

Source of Truth Priority

1. Implementation code (actual behavior) 2. Tests (expected behavior with assertions) 3. Type definitions / schemas (declared contracts) 4. Existing documentation (may be stale — verify)

---

Phase 2: Author

Entry Format

Every documented item uses a consistent structure:

### methodName

**Type**: `(param1: string, param2?: number) => Promise<Result>`
**Since**: v2.1.0
**Deprecated**: No

**Description**:
Brief explanation of purpose and behavior.

**Parameters**:

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | What this parameter controls |
| `param2` | `number` | No | `10` | What this parameter controls |

**Returns**: `Promise<Result>` — description of return value

**Throws**:
- `ValidationError` — when param1 is empty
- `TimeoutError` — when operation exceeds 30s

**Examples**:

Basic usage:
\`\`\`typescript
const result = await methodName("value");
\`\`\`

With options:
\`\`\`typescript
const result = await methodName("value", 20);
\`\`\`

**See Also**: [relatedMethod](#relatedmethod), [Configuration Guide](#configuration)

Writing Rules

1. Document behavior, not implementation — what it does, not how 2. Every parameter gets a row — no exceptions, even obvious ones 3. Every entry gets an example — at least one working code sample 4. State constraints explicitly — valid ranges, length limits, format requirements 5. Cross-reference related items — link to related methods, configs, and error codes

---

Phase 3: Verify

Verification Methods

Accuracy Checklist

• [ ] All signatures match current implementation
• [ ] All default values are correct
• [ ] All error conditions are documented
• [ ] All examples work against current version
• [ ] No removed features are still documented
• [ ] No new features are undocumented

---

Phase 4: Organize

Document Hierarchy

1. Overview          — What this API/system does, quick orientation
2. Quick Reference   — Cheat sheet of common operations with examples
3. Authentication    — How to authenticate (if applicable)
4. Detailed Reference — Complete documentation, grouped logically
5. Error Reference   — All error codes with causes and fixes
6. Glossary          — Terms specific to this system
7. Changelog         — What changed in each version

Navigation Aids

• Table of contents with deep linking at the top
• Alphabetical index for large reference sets
• Category grouping for logical discovery
• Search keywords embedded in headings and descriptions
• Version badges on entries added or changed in recent versions

---

Phase 5: Maintain

Versioning Strategy

• Tag every entry with the version it was introduced (**Since**: v2.1.0)
• Mark deprecations with migration guidance (**Deprecated**: v3.0 — use newMethod instead)
• Maintain a changelog section at the bottom of reference docs
• Separate docs by major version when breaking changes accumulate

Update Triggers

Reference documentation must be updated when:

• A public API signature changes
• A new parameter, endpoint, or command is added
• Default values or constraints change
• Features are deprecated or removed
• Error codes or behaviors change

---

Content Patterns

Parameter Tables

Always use tables for parameters — never inline lists:

Status Code Tables

Configuration Blocks

# config.yaml
server:
  port: 3000          # Port to listen on (1024-65535)
  host: "0.0.0.0"     # Bind address
  timeout: 30000      # Request timeout in ms
  max_body_size: "1mb" # Maximum request body size

Anti-Patterns

• Documenting internal/private interfaces that can change without notice
• Using "obvious" or "self-explanatory" instead of writing a real description
• Omitting error documentation because "it's clear from the types"
• Copy-pasting examples without verifying they still work
• Mixing tutorial-style narrative into reference entries (keep them separate)
• Letting documentation fall behind implementation for more than one release

Documentation Patterns Reference

API doc structure, glossary patterns, cross-referencing techniques, versioned documentation, parameter tables, and configuration guide patterns.

---

API Documentation Structure

REST API Entry Template

## POST /api/users

Create a new user account.

**Authentication**: Required (Bearer token)
**Rate Limit**: 10 requests/minute per token
**Since**: v2.0.0

### Request

**Headers**:

| Header | Required | Description |
|--------|----------|-------------|
| `Authorization` | Yes | Bearer token |
| `Content-Type` | Yes | Must be `application/json` |
| `Idempotency-Key` | No | Prevents duplicate creation |

**Body**:

| Field | Type | Required | Constraints | Description |
|-------|------|----------|-------------|-------------|
| `name` | `string` | Yes | 1-100 chars | Display name |
| `email` | `string` | Yes | Valid email format | Unique email address |
| `role` | `string` | No | One of: `user`, `admin` | Default: `user` |

**Example**:
\`\`\`json
{
  "name": "Jane Developer",
  "email": "jane@example.com",
  "role": "admin"
}
\`\`\`

### Response

**Success (201 Created)**:
\`\`\`json
{
  "id": "usr_abc123",
  "name": "Jane Developer",
  "email": "jane@example.com",
  "role": "admin",
  "created_at": "2026-01-15T10:30:00Z"
}
\`\`\`

**Errors**:

| Status | Code | Description |
|--------|------|-------------|
| 400 | `invalid_email` | Email format is invalid |
| 409 | `email_exists` | Email already registered |
| 422 | `validation_error` | One or more fields failed validation |
| 429 | `rate_limited` | Rate limit exceeded |

**Error response format**:
\`\`\`json
{
  "error": {
    "code": "email_exists",
    "message": "A user with this email already exists",
    "field": "email"
  }
}
\`\`\`

GraphQL API Entry Template

## Query: users

Fetch a paginated list of users with optional filtering.

**Authentication**: Required
**Since**: v2.1.0

### Schema

\`\`\`graphql
type Query {
  users(
    filter: UserFilter
    pagination: PaginationInput
    sort: UserSort
  ): UserConnection!
}

input UserFilter {
  role: UserRole
  createdAfter: DateTime
  search: String
}

input PaginationInput {
  first: Int = 20
  after: String
}

enum UserSort {
  CREATED_AT_ASC
  CREATED_AT_DESC
  NAME_ASC
}
\`\`\`

### Example Query

\`\`\`graphql
query {
  users(filter: { role: ADMIN }, pagination: { first: 10 }) {
    edges {
      node {
        id
        name
        email
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
\`\`\`

CLI Command Entry Template

## cortex deploy

Deploy the application to the specified environment.

**Since**: v1.0.0

### Usage

\`\`\`bash
cortex deploy [environment] [flags]
\`\`\`

### Arguments

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `environment` | No | `staging` | Target environment |

### Flags

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--config` | `-c` | `string` | `./deploy.yaml` | Config file path |
| `--dry-run` | | `bool` | `false` | Show what would be deployed |
| `--timeout` | `-t` | `duration` | `5m` | Deploy timeout |
| `--force` | `-f` | `bool` | `false` | Skip confirmation prompt |
| `--verbose` | `-v` | `bool` | `false` | Verbose output |

### Examples

\`\`\`bash
# Deploy to staging (default)
cortex deploy

# Deploy to production with confirmation
cortex deploy production

# Dry run to see what would change
cortex deploy production --dry-run

# Deploy with custom config
cortex deploy staging -c ./custom-deploy.yaml
\`\`\`

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Configuration error |
| 3 | Timeout |
| 4 | Authentication failure |

---

Parameter Tables

Standard Parameter Table

Always use this format for consistency:

Nested Parameter Tables

For complex objects, use indentation or separate tables:

### Options

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `connection` | `object` | Yes | — | Database connection settings |
| `connection.host` | `string` | Yes | — | Database hostname |
| `connection.port` | `number` | No | `5432` | Database port |
| `connection.ssl` | `boolean` | No | `true` | Enable TLS |
| `pool` | `object` | No | — | Connection pool settings |
| `pool.min` | `number` | No | `2` | Minimum pool size |
| `pool.max` | `number` | No | `10` | Maximum pool size |

Enum Tables

When a parameter accepts specific values, document each:

### Status Values

| Value | Description | Transitions to |
|-------|-------------|---------------|
| `draft` | Initial state, editable | `review` |
| `review` | Under review, read-only | `approved`, `draft` |
| `approved` | Approved, awaiting publish | `published` |
| `published` | Live and visible to users | `archived` |
| `archived` | No longer visible | `draft` |

---

Configuration Guide Patterns

Configuration File Reference

## Configuration Reference

Configuration is loaded from `config.yaml` in the project root. All values can
be overridden with environment variables using the `APP_` prefix.

### Server

\`\`\`yaml
server:
  port: 3000          # APP_SERVER_PORT — Port to listen on (1024-65535)
  host: "0.0.0.0"     # APP_SERVER_HOST — Bind address
  timeout: 30000      # APP_SERVER_TIMEOUT — Request timeout in ms
  cors:
    enabled: true     # APP_SERVER_CORS_ENABLED — Enable CORS
    origins:          # APP_SERVER_CORS_ORIGINS — Comma-separated origins
      - "https://app.example.com"
\`\`\`

| Key | Type | Default | Env Var | Description |
|-----|------|---------|---------|-------------|
| `server.port` | `integer` | `3000` | `APP_SERVER_PORT` | TCP port (1024-65535) |
| `server.host` | `string` | `"0.0.0.0"` | `APP_SERVER_HOST` | Bind address |
| `server.timeout` | `integer` | `30000` | `APP_SERVER_TIMEOUT` | Request timeout (ms) |
| `server.cors.enabled` | `boolean` | `true` | `APP_SERVER_CORS_ENABLED` | Enable CORS headers |
| `server.cors.origins` | `string[]` | `["*"]` | `APP_SERVER_CORS_ORIGINS` | Allowed origins |

Environment-Specific Overrides

### Environment Defaults

Values that change by environment:

| Key | Development | Staging | Production |
|-----|------------|---------|------------|
| `server.port` | `3000` | `8080` | `8080` |
| `database.pool.max` | `5` | `20` | `50` |
| `logging.level` | `debug` | `info` | `warn` |
| `cache.ttl` | `0` (disabled) | `300` | `3600` |

---

Glossary Patterns

Glossary Entry Format

## Glossary

**Bearer Token**: An access token included in the `Authorization` header as
`Bearer <token>`. Obtained from the [authentication endpoint](#post-apiauth).

**CDE (Cardholder Data Environment)**: The systems, networks, and processes that
store, process, or transmit cardholder data. See [PCI DSS scope](#pci-dss-scope).

**Idempotency Key**: A unique string sent with mutating requests to prevent
duplicate operations. The server guarantees that requests with the same key
produce the same result. See [idempotency guide](#idempotency).

Glossary Rules

• Sort alphabetically
• Include the abbreviation expansion if applicable
• Link to the relevant documentation section
• Keep definitions to 1-3 sentences
• Use consistent formatting (bold term, colon, definition)

---

Cross-Referencing Techniques

In-Document Links

See the [authentication section](#authentication) for details on token management.

Cross-Document Links

For deployment configuration, see the [Operations Guide](./operations.md#deployment).

"See Also" Blocks

Place at the end of each entry:

**See Also**:
- [Related Method](#related-method) — does something similar for a different use case
- [Configuration Guide](#configuration) — configure the defaults for this method
- [Error Codes](#error-codes) — full list of errors this method can return

Back-References

When documenting errors, link back to the operations that produce them:

### Error: `rate_limited` (429)

**Produced by**: [POST /api/users](#post-apiusers), [POST /api/orders](#post-apiorders)

**Description**: Request rate limit exceeded for your API token.

**Resolution**: Wait for the duration specified in the `Retry-After` header.

---

Versioned Documentation

Version Badges

Mark entries with the version they were introduced or changed:

### newMethod() <Badge text="v2.1.0" />

Description...

### legacyMethod() <Badge text="Deprecated in v3.0" type="warning" />

**Deprecated**: Use [newMethod](#newmethod) instead. Will be removed in v4.0.

In Markdown (Without Components)

### newMethod()

> **Added in v2.1.0**

### legacyMethod()

> **Deprecated in v3.0** — Use [newMethod](#newmethod) instead. Removal planned for v4.0.

Changelog Section

Place at the bottom of reference docs:

## Changelog

### v3.0.0 (2026-02-01)
- **Breaking**: Removed `legacyMethod()` — use `newMethod()` instead
- **Breaking**: Changed `timeout` default from 60s to 30s
- Added `batchProcess()` method

### v2.1.0 (2025-11-15)
- Added `newMethod()` for improved performance
- Deprecated `legacyMethod()` (removal in v4.0)
- Added `retries` parameter to `connect()`

### v2.0.0 (2025-08-01)
- Initial stable release

---

Searchable Indexing

Keyword Embedding

Include search terms that users might use but that are not in the heading:

### connect()
<!-- keywords: open connection, establish session, initialize client, setup -->

Opens a connection to the server.

Alias Documentation

When the same concept has multiple names:

### Rate Limiting (Throttling)

Also known as: request throttling, API rate control, traffic shaping.

Index Table

For large reference docs, provide an alphabetical index:

## Index

| Term | Section |
|------|---------|
| Authentication | [Authentication](#authentication) |
| Authorization header | [Headers](#headers) |
| Bearer token | [Authentication](#authentication), [Glossary](#glossary) |
| CORS | [Configuration](#cors-configuration) |
| Rate limiting | [Rate Limiting](#rate-limiting) |
| Retry-After header | [Rate Limiting](#rate-limiting), [Headers](#headers) |