Docs Voice

Tone by Page Type

Note: Pitfall and DeepDive components can use slightly more conversational phrasing ("You might wonder...", "It might be tempting...") even in Reference pages, since they're explanatory asides.

Avoiding Jargon

Pattern: Explain behavior first, then name it.

✅ "React waits until all code in event handlers runs before processing state updates. This is called batching."

❌ "React uses batching to process state updates atomically."

Terms to avoid or explain:

Allowed technical terms in Reference pages:

• "stale closures" - standard JS/React term, can be used in Caveats
• "stable identity" - React term for consistent object references across renders
• "reactive" - React term for values that trigger re-renders when changed
• These don't need explanation in Reference pages (readers are expected to know them)

Use established analogies sparingly—once when introducing a concept, not repeatedly:

Common Prose Patterns

Wrong vs Right code:

\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`

\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`

Table comparisons:

| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |

Linking:

[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)

Code Style

• Prefer JSX over createElement
• Use const/let, never var
• Prefer named function declarations for top-level functions
• Arrow functions for callbacks that need this preservation

Version Documentation

When APIs change between versions:

Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`

In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`

Patterns:

• "Starting in React 19..." for new APIs
• "In older versions of React..." for legacy patterns