docs-writer-reference

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.

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/}

Examples of correct code for this rule:

// checkmark All dependencies included
useEffect(() => {
  console.log(count);
}, [count]);

Troubleshooting {/troubleshooting/}

[Problem description] {/problem-slug/}

[Solution]

Options {/options/}

[Configuration options if applicable]

**Key characteristics:**
- Intro is a single "Validates that..." sentence
- Uses "Invalid"/"Valid" sections with emoji-prefixed code comments
- Rule Details explains "why" not just "what"

---

### Type F: Index/Category

**When to use:** Overview pages listing multiple APIs in a category

```mdx
---
title: "Built-in React [Type]"
---

<Intro>

*Concept* let you [purpose]. Brief scope statement.

</Intro>

---

## Category Name {/*category-name*/}

*Concept* explanation with [Learn section link](/learn/topic).

To [action], use one of these [Type]:

* [`apiName`](/reference/react/apiName) lets you [action].
* [`apiName`](/reference/react/apiName) declares [thing].

```js
function Example() {
  const value = useHookName(args);
}

---

Your own [Type] {/your-own-type/}

You can also define your own as JavaScript functions.

**Key characteristics:**
- Title format: "Built-in React [Type]"
- Italicized concept definitions
- Horizontal rules between sections
- Closes with "Your own [Type]" section

---

## Advanced Patterns

### Multi-Function Documentation

**When to use:** When a hook returns a function that needs its own documentation (useState's setter, useReducer's dispatch)

```md
### `hookName(args)` {/*hookname*/}

[Main hook documentation]

#### Parameters {/*parameters*/}
#### Returns {/*returns*/}
#### Caveats {/*caveats*/}

---

### `set` functions, like `setSomething(nextState)` {/*setstate*/}

The `set` function returned by `hookName` lets you [action].

#### Parameters {/*setstate-parameters*/}
#### Returns {/*setstate-returns*/}
#### Caveats {/*setstate-caveats*/}

Key conventions:

• Horizontal rule (---) separates main hook from returned function
• Heading IDs include prefix: {/*setstate-parameters*/} vs {/*parameters*/}
• Use generic names: "set functions" not "setCount"

---

Compound Return Objects

When to use: When a function returns an object with multiple properties/methods (createContext)

### `createContext(defaultValue)` {/*createcontext*/}

[Main function documentation]

#### Returns {/*returns*/}

`createContext` returns a context object.

**The context object itself does not hold any information.** It represents...

* `SomeContext` lets you provide the context value.
* `SomeContext.Consumer` is an alternative way to read context.

---

### `SomeContext` Provider {/*provider*/}

[Documentation for Provider]

#### Props {/*provider-props*/}

---

### `SomeContext.Consumer` {/*consumer*/}

[Documentation for Consumer]

#### Props {/*consumer-props*/}

---

Writing Patterns

Opening Lines by Page Type

Page Type	Pattern	Example
Hook	`hookName` is a React Hook that lets you [action].	"useState is a React Hook that lets you add a state variable to your component."
Component	`<ComponentName>` lets you [action].	"<Suspense> lets you display a fallback until its children have finished loading."
API	`apiName` lets you [action].	"memo lets you skip re-rendering a component when its props are unchanged."
Configuration	The `optionName` option [controls/specifies/determines] [what].	"The target option specifies which React version the compiler generates code for."
Directive	`'directive'` [marks/opts/prevents] [what] for [purpose].	"'use server' marks a function as callable from the client."
ESLint Rule	Validates that [condition].	"Validates that dependency arrays for React hooks contain all necessary dependencies."

---

Parameter Patterns

Simple parameter:

* `paramName`: Description of what it does.

Optional parameter:

* **optional** `paramName`: Description of what it does.

Parameter with special function behavior:

* `initialState`: The value you want the state to be initially.

---

*Content truncated.*