Docs Writer Reference

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.)

---