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

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

```markdown
---
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](/reference/related-symbol) - Brief description
- [AnotherSymbol](/reference/another-symbol) - 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:**
```markdown
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:**
```markdown
| Name | Type | Description |
|------|------|-------------|
| `userId` | `string` | Unique user identifier |
| `options` | `Options` | Configuration object |
```

**Avoid:**
```markdown
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

```markdown
## Example

### Basic Usage

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

### With Options

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

### Include Setup and Context

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

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

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

## Return Value Documentation

### Simple Returns

```markdown
## Returns

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

### Complex Returns

```markdown
## Returns

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

### Error Conditions

```markdown
## Errors

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

## API Reference Specifics

### HTTP Endpoints

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

```json
{
  "id": "usr_a1b2c3d4",
  "name": "Jane Smith",