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

Resource	Purpose	Load when
references/documentation-patterns.md	API doc structure, glossary patterns, cross-referencing, versioned docs, parameter tables, configuration guides	Structuring any reference document

---

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

What to verify	How
Method signatures	Compare against source code type definitions
Default values	Check source code initializers
Error conditions	Read implementation and test assertions
Examples	Run them or trace them against the code
Deprecated items	Check for deprecation markers in source

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:

Name	Type	Required	Default	Description
timeout	number	No	30000	Request timeout in milliseconds
retries	number	No	3	Number of retry attempts

Status Code Tables

Code	Name	Description	Resolution
400	Bad Request	Invalid input parameters	Check request body against schema
401	Unauthorized	Missing or invalid auth token	Re-authenticate and retry
429	Rate Limited	Too many requests	Back off and retry after Retry-After header

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