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