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. To confirm reference is the right type — rather than a tutorial, how-to, or explanation — see 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 - Brief description
• AnotherSymbol - 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.