Canonical source: docs/claude/docs-style-guide.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.
Ready Practice Docs — House Style
The standard for all customer-facing documentation (the Set-Up journey, feature reference, docs/features/, guides). Grounded in how Stripe, Anthropic, Jane, and SimplePractice write. A page is not done until it passes every rule below. Register: Jane's warmth + SimplePractice's plain calm, with Stripe/Anthropic's rigor on dense RCM/billing pages.
The rules
Structure
- Every page opens with 2–3 sentences of what / why / outcome — what this page lets the organization accomplish, and why it matters or when to use it. Never open a page with a heading immediately followed by a bullet.
- Every section opens with 1–3 sentences of prose before any list, table, or steps. A list never appears cold — introduce what it contains and why.
- Why before how. State a feature's purpose and when to use it before the click-path. For each field/setting listed, give its purpose, not just its name.
Steps & instructions 4. Each step is a full sentence that names the bold on-screen label and states the result. e.g. "Go to Settings → Billing and add your Tax ID. Once saved, it appears on every superbill automatically." — not "Add Tax ID." 5. State the stakes when an action is required or has consequences ("this is required before you can…", "claims are denied without this"). 6. Reference exact UI labels in bold, with the full navigation path.
Concepts & terms 7. Define every domain term on first use, inline — a parenthetical gloss or "X is a Y that does Z" (NPI, taxonomy, superbill, rendering provider, panel, membership allowance…). Assume the reader has never done this before. 8. Prefer a plain-language analogy or a concrete worked example over abstraction (e.g. "an availability block from 8:00 AM to 5:00 PM that repeats each weekday").
Voice 9. Second person, present tense, contractions, ~8th-grade reading level. Warm but not padded — a helpful colleague, not a manual, not a marketer. 10. Paragraphs ≤ 3–4 sentences, one idea each. Sentences short-to-medium.
Scannability vs depth
11. Typed callouts, not more bullets, for out-of-band info: Tip (a better way) · Note (a caveat/behavior) · Warning (something that breaks/denies) · Ask Atlas (the on-platform shortcut). Keep the happy path in prose; push edge cases into callouts or an "Optional:" / collapsible block.
12. Tables only for genuinely parallel reference data (roles × permissions, fee schedules, field references), always introduced by a sentence. Never use a bare bullet list in place of an explanation.
13. Every screenshot gets a caption stating what to notice; annotate the specific control that matters. Use demo-clinic data only.
Closers 14. Every page ends with intent-labeled "Next steps" (verb + benefit per link). Onboarding-step pages end with an explicit "Next up: …". Never a dead stop.
The bar (before / after)
Before (too thin): "Provider Credentials — each rendering provider's NPI and taxonomy. Claims are denied without them."
After (house style): a 2–3 sentence what/why opener → each term defined inline → a full-sentence click-path stating the result → the denial consequence in a Warning callout with a symptom to recognize → an Ask Atlas shortcut → an intent-labeled next step. One thin bullet becomes a section a brand-new front-desk hire can execute without already knowing insurance billing. That is the bar.