/docs-writer-reference

name: docs-writer-reference
description: Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack.

Reference Page Writer

Quick Reference

Page Type Decision Tree

1. Is it a Hook? Use **Type A (Hook/Function)** 2. Is it a React component (`<Something>`)? Use **Type B (Component)** 3. Is it a compiler configuration option? Use **Type C (Configuration)** 4. Is it a directive (`'use something'`)? Use **Type D (Directive)** 5. Is it an ESLint rule? Use **Type E (ESLint Rule)** 6. Is it listing multiple APIs? Use **Type F (Index/Category)**

Component Selection

For component selection and patterns, invoke `/docs-components`.

---

Voice & Style

**Voice:** Authoritative technical reference writer **Tone:** Precise, comprehensive, neutral

For tone, capitalization, jargon, and prose patterns, invoke `/docs-voice`.

**Do:**

• Start with single-line description: "`useState` is a React Hook that lets you..."
• Include Parameters, Returns, Caveats sections for every API
• Document edge cases most developers will encounter
• Use section dividers between major sections
• Include "See more examples below" links
• Be assertive, not hedging - "This is designed for..." not "This helps avoid issues with..."
• State facts, not benefits - "The callback always accesses the latest values" not "This helps avoid stale closures"
• Use minimal but meaningful names - `onEvent` or `onTick` over `onSomething`

**Don't:**

• Skip the InlineToc component
• Omit error cases or caveats
• Use conversational language
• Mix teaching with reference (that's Learn's job)
• Document past bugs or fixed issues
• Include niche edge cases (e.g., `this` binding, rare class patterns)
• Add phrases explaining "why you'd want this" - the Usage section examples do that
• Exception: Pitfall and DeepDive asides can use slightly conversational phrasing

---

Page Templates

Type A: Hook/Function

**When to use:** Documenting React hooks and standalone functions (useState, useEffect, memo, lazy, etc.)

---
title: hookName
---

<Intro>

`hookName` is a React Hook that lets you [brief description].

```js
const result = hookName(arg)

</Intro>

<InlineToc />

---

Reference {/*reference*/}

`hookName(arg)` {/*hookname*/}

Call `hookName` at the top level of your component to...

[signature example with annotations]

[See more examples below.](#usage)

Parameters {/*parameters*/}

• `arg`: Description of the parameter.

Returns {/*returns*/}

Description of return value.

Caveats {/*caveats*/}

• Important caveat about usage.

---

Usage {/*usage*/}

Common Use Case {/*common-use-case*/}

Explanation with Sandpack examples...

---

Troubleshooting {/*troubleshooting*/}

Common Problem {/*common-problem*/}

How to solve it...

---

### Type B: Component

**When to use:** Documenting React components (Suspense, Fragment, Activity, StrictMode)

```mdx
---
title: <ComponentName>
---

<Intro>

`<ComponentName>` lets you [primary action].

```js
<ComponentName prop={value}>
  <Children />
</ComponentName>

</Intro>

<InlineToc />

---

Reference {/*reference*/}

`<ComponentName>` {/*componentname*/}

[Component purpose and behavior]

Props {/*props*/}

• `propName`: Description of the prop...
• **optional** `optionalProp`: Description...

Caveats {/*caveats*/}

• [Caveats specific to this component]

**Key differences from Hook pages:**
- Title uses JSX syntax: `<ComponentName>`
- Uses `#### Props` instead of `#### Parameters`
- Reference heading uses JSX: `` ### `<ComponentName>` ``

---

### Type C: Configuration

**When to use:** Documenting React Compiler configuration options

```mdx
---
title: optionName
---

<Intro>

The `optionName` option [controls/specifies/determines] [what it does].

</Intro>

```js
{
  optionName: 'value' // Quick example
}

<InlineToc />

---

Reference {/*reference*/}

`optionName` {/*optionname*/}

[Description of the option's purpose]

Type {/*type*/}

'value1' | 'value2' | 'value3'

Default value {/*default-value*/}

`'value1'`

Options {/*options*/}

• **`'value1'`** (default): Description
• **`'value2'`**: Description
• **`'value3'`**: Description

Caveats {/*caveats*/}

• [Usage caveats]

---

### Type D: Directive

**When to use:** Documenting directives like 'use server', 'use client', 'use memo'

```mdx
---
title: "'use directive'"
titleForTitleTag: "'use directive' directive"
---

<RSC>

`'use directive'` is for use with [React Server Components](/reference/rsc/server-components).

</RSC>

<Intro>

`'use directive'` marks [what it marks] for [purpose].

```js {1}
function MyComponent() {
  'use directive';
  // ...
}

</Intro>

<InlineToc />

---

Reference {/*reference*/}

`'use directive'` {/*use-directive*/}

Add `'use directive'` at the beginning of [location] to [action].

Caveats {/*caveats*/}

• `'use directive'` must be at the very beginning...
• The directive must be written with single or double quotes, not backticks.
• [Other placement/syntax caveats]

**Key characteristics:**
- Title includes quotes: `title: "'use server'"`
- Uses `titleForTitleTag` for browser tab title
- `<RSC>` block appears before `<Intro>`
- Caveats focus on placement and syntax requirements

---

### Type E: ESLint Rule

**When to use:** Documenting ESLint plugin rules

```mdx
---
title: rule-name
---

<Intro>
Validates that [what the rule checks].
</Intro>

## Rule Details {/*rule-details*/}

[Explanation of why this rule exists and React's underlying assumptions]

## Common Violations {/*common-violations*/}

[Description of violation patterns]

### Invalid {/*invalid*/}

Examples of incorrect code for this rule:

```js
// X Missing dependency
useEffect(() => {
  console.log(count);
}, []); // Missing 'count'

Valid {/*valid*/}

Exampl