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