/reference-docs

name: reference-docs
description: Reference documentation patterns for API and symbol documentation. Use when writing reference docs, API docs, parameter tables, or technical specifications. Triggers on reference docs, API reference, function reference, parameters table, symbol documentation.
user-invocable: false

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. To confirm reference is the right type — rather than a tutorial, how-to, or explanation — see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

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](/reference/related-symbol) - Brief description
• [AnotherSymbol](/reference/another-symbol) - Brief description

## Writing Principles

### Describe, and Only Describe

Reference is austere, neutral, and authoritative — a map the reader can trust without independent verification. Its one job is to describe the machinery: commands, options, parameters, return values, limits, warnings. It does not instruct (that's How-To), teach (Tutorial), or argue (Explanation). When you feel the urge to explain *why* or walk the reader through a task, link out instead of inlining it; a digression interrupts and obscures the facts the reader came to consult.

### Structure Mirrors the Product

> "The structure of the documentation should mirror the structure of the product."

Organise reference so a reader can navigate the code and the docs in parallel — one reference entry per module, class, endpoint, or command, in the product's own order. Don't impose a narrative or thematic structure the product doesn't have; consistency of placement is what makes reference fast to consult.

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

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

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

|