Reference Docs

Reference Documentation Patterns

Reference documentation is information-oriented - helping experienced users find precise technical details quickly. This skill provides patterns for writing clear, scannable reference pages.

Dependency: Always use this skill in conjunction with docs-style for core writing principles.

Purpose and Audience

Document Structure Template

Use this template when creating reference documentation:

---
title: "[Symbol/API Name]"
description: "One-line description of what it does"
[Name]
Brief description (1-2 sentences). State what it is and its primary purpose.
Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | string | Yes | What this parameter controls |
| param2 | number | No | Optional behavior modification. Default: 10 |
Returns
| Type | Description |
|------|-------------|
| ReturnType | What the function returns and when |
Example

// Complete, runnable example showing common use case const result = symbolName({ param1: 'realistic-value', param2: 42 });

console.log(result); // Expected output: { ... }

Related
RelatedSymbol - Brief description
AnotherSymbol - Brief description

Writing Principles

Brevity Over Explanation

Do:

Returns the user's display name.

Avoid:

This function is useful when you need to get the user's display name
because it handles all the edge cases for you automatically.

Scannable Tables, Not Prose

Do:

| Name | Type | Description |
|------|------|-------------|
| userId | string | Unique user identifier |
| options | Options | Configuration object |

Avoid:

The first parameter is userId, which should be a string containing
the unique user identifier. The second parameter is options, which
is an Options object containing the configuration.

Consistent Format Across Entries

All reference pages for similar items should follow identical structure:

Every Example Must Be Runnable

Code Example Patterns

Show Common Use Case First

## Example
Basic Usage

With Options

Include Setup and Context

// Initialize client (required once per application) const client = new Client({ apiKey: process.env.API_KEY });

// Now use the function const result = await client.users.list();

Use Realistic Values

Do: userId: 'usr_a1b2c3d4' Avoid: userId: 'foo'

Do: email: 'jane.smith@company.com' Avoid: email: 'test@test.com'

Parameter Documentation Patterns

Required vs Optional

Clearly indicate which parameters are required:

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| apiKey | string | Yes | - | Your API key |
| timeout | number | No | 30000 | Request timeout in ms |
| retries | number | No | 3 | Number of retry attempts |

Complex Types

For object parameters, document the shape:

## Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| options | UserOptions | No | Configuration options |
UserOptions
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| includeDeleted | boolean | No | Include soft-deleted users |
| fields | string[] | No | Fields to return |
| limit | number | No | Maximum results (default: 100) |

Enum Values

Document allowed values clearly:

| Name | Type | Values | Description |
|------|------|--------|-------------|
| status | string | active, pending, suspended | User account status |

Return Value Documentation

Simple Returns

## Returns
User - The requested user object, or null if not found.

Complex Returns

## Returns
| Property | Type | Description |
|----------|------|-------------|
| data | User[] | Array of user objects |
| pagination | Pagination | Pagination metadata |
| total | number | Total matching records |

Error Conditions

## Errors
| Error | Condition |
|-------|-----------|
| NotFoundError | User does not exist |
| UnauthorizedError | Invalid or expired API key |
| RateLimitError | Too many requests |

API Reference Specifics

HTTP Endpoints

## Endpoint

Path Parameters
| Name | Type | Description |
|------|------|-------------|
| userId | string | The user's unique identifier |
Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| fields | string | No | Comma-separated list of fields |
Headers
| Name | Required | Description |
|------|----------|-------------|
| Authorization | Yes | Bearer token |
| X-Request-ID | No | Request tracking ID |
Response

Component/Props Reference

For UI components:

## Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Button size |
| disabled | boolean | false | Disable interactions |
| onClick | () => void | - | Click handler |
Slots
| Name | Description |
|------|-------------|
| default | Button content |
| icon | Icon to display before text |

Related Links Section

Always include links to related content:

## Related
createUser - Create a new user
updateUser - Modify user properties
deleteUser - Remove a user
User Authentication Guide - How authentication works

Gates (completion order)

Use this sequenced workflow before treating a reference page as complete. Finish step *n* before *n+1*; each step has a Pass you can check on the written page alone (no “I verified internally”).

1. Structure — Sections match your project template (typically Parameters, Returns, Example, Related; HTTP docs add Endpoint, Path/Query, Headers, Response). Pass: every required section exists, or a one-line omission note appears under Related (e.g. “No query parameters”). 2. Tables — Parameters/returns/errors use tables with consistent columns per Consistent Format Across Entries and Required vs Optional. Pass: no blank Description cells; no TBD / ??? for shipped APIs. 3. Runnable example — At least one example meets Every Example Must Be Runnable and Use Realistic Values. Pass: imports included; user-visible strings are realistic (not generic foo/bar unless the API is illustrative-only). 4. Related — Pass: ## Related contains ≥1 Markdown link to another reference or guide, or one explicit sentence that there are no related symbols.

Checklist for Reference Pages

After the Gates (completion order) above, confirm:

import { symbolName } from 'package';
// Complete, runnable example showing common use case
const result = symbolName({
  param1: 'realistic-value',
  param2: 42
});
console.log(result);
// Expected output: { ... }