docs-voice

# React Docs Voice & Style

## Universal Rules

- **Capitalize React terms** when referring to the React concept in headings or as standalone concepts:
  - Core: Hook, Effect, State, Context, Ref, Component, Fragment
  - Concurrent: Transition, Action, Suspense
  - Server: Server Component, Client Component, Server Function, Server Action
  - Patterns: Error Boundary
  - Canary: Activity, View Transition, Transition Type
  - **In prose:** Use lowercase when paired with descriptors: "state variable", "state updates", "event handler". Capitalize when the concept stands alone or in headings: "State is isolated and private"
  - General usage stays lowercase: "the page transitions", "takes an action"
- **Product names:** ESLint, TypeScript, JavaScript, Next.js (not lowercase)
- **Bold** for key concepts: **state variable**, **event handler**
- **Italics** for new terms being defined: *event handlers*
- **Inline code** for APIs: `useState`, `startTransition`, `<Suspense>`
- **Avoid:** "simple", "easy", "just", time estimates
- Frame differences as "capabilities" not "advantages/disadvantages"
- Avoid passive voice and jargon

## Tone by Page Type

| Type | Tone | Example |
|------|------|---------|
| Learn | Conversational | "Here's what that looks like...", "You might be wondering..." |
| Reference | Technical | "Call `useState` at the top level...", "This Hook returns..." |
| Blog | Accurate | Focus on facts, not marketing |

**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:**
| Jargon | Plain Language |
|--------|----------------|
| atomic | all-or-n