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 Who: Experienced users seeking specific information Goal: Quick lookup of technical details Mode: Not for learning, for looking up Expectation: Brevity, consistency, completeness 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

```language import { symbolName } from 'package';

// 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

• State facts, not rationale
• Avoid "why" - save that for Explanation docs
• Cut unnecessary words

Do: ```markdown 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:

Same heading order Same table columns Same code example format Same related links section Every Example Must Be Runnable Include all imports Show complete, working code Use realistic values (not "foo", "bar", "test123") Include expected output when helpful Code Example Patterns Show Common Use Case First

Example

Basic Usage

```typescript const user = await getUser('user-123'); console.log(user.name);

With Options const user = await getUser('user-123', { includeMetadata: true, fields: ['name', 'email', 'role'] });

Include Setup and Context

markdowntypescript import { Client } from '@example/sdk';

// 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:

``markdown | 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

```http GET /api/v1/users/{userId}

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 { "id": "usr_a1b2c3d4", "name": "Jane Smith", "email": "jane@company.com" }

Component/Props Reference

For UI components:

```markdown

Props

Slots

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

Checklist for Reference Pages

Before considering a reference page complete:

Title matches the symbol/API name exactly Description is one clear sentence All parameters documented with types Required vs optional clearly marked Default values specified for optional parameters Return type and structure documented At least one complete, runnable example Example uses realistic values Related pages linked Format matches other reference pages in the docs