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.) ```mdx --- 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... ```js [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*/} Examples of correct code for this rule: ```js // 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](/learn/topic) 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) ```md ### `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 |