Style guide evaluation summary
Evaluation of three sample docs against the STYLE_GUIDE.md (aligned with Microsoft Writing Style Guide). Audited files: web-sdk/guides/ambient-implementation.mdx, mobile-sdk/ambient-guides/create-session.mdx, documentation/getting-started.mdx.
Checklist results
| Check | ambient-implementation | create-session | getting-started |
|---|
| Brevity / voice | Callout uses “you can pass”; otherwise direct | ”You can optionally provide,” “you can use,” “you can provide,” “you can start” | Minimal weak openings in sampled section |
| Capitalization (sentence-style headings) | Fail: “Controlled Session Management,” “Update Encounter and Ambient Options,” “Next Steps” (title case) | Fail: “What Will You Learn?,” “Create An Ambient Session,” “Provide Clinical Context (Optional but Recommended),” etc. | Fail: “What You Need Before Starting,” “Step 1: Choose Your Integration Path,” “Step 2: Integration Setup For API And SDKs,” “Step 3:Advance Configuration (Optional But Recommended)“ |
| Punctuation (no period on short headings/list items) | Pass: headings have no trailing periods | Pass | Pass |
| Oxford comma | Pass (e.g. “visit_type, encounter_type, provider_role, and the free-text fields”) | Pass | Pass |
| Em dashes | Pass: none found | Pass: none found | Pass: none found |
| Inclusivity (gender-neutral, no master/slave) | Pass: no gendered generic pronouns or problematic terms | Pass | Pass |
| Scannability (clear headings, short paragraphs) | Pass: clear H2s, reasonable paragraph length | Pass: Quick Summary, clear sections | Pass: steps and cards |
Prioritized gaps
- High: Typo and spacing in
documentation/getting-started.mdx: “Step 3:Advance Configuration” should be “Step 3: Advanced configuration” (fix “Advance” → “Advanced,” add space after colon, sentence-style for subphrase).
- Medium: Heading capitalization is title case across all three docs. Per style guide, use sentence-style for H2/H3 (e.g. “Controlled session management,” “Update encounter and ambient options,” “What will you learn?”).
- Low: Several “You can” openings in create-session and one in ambient-implementation; can be revised to stronger verbs in a future pass.
Actions taken
- Style guide: Added STYLE_GUIDE.md with voice, punctuation, capitalization, contractions, strong writing, scannable content, bias-free, global, and terminology rules.
- AGENTS.md: Content Guidelines updated to reference STYLE_GUIDE.md; New Doc Writing Rule includes a Style step; Release notes section links to style guide.
- Fixes applied:
- documentation/getting-started.mdx: “Step 3:Advance Configuration (Optional But Recommended)” → “Step 3: Advanced configuration (optional but recommended)”; all audited H2s set to sentence-style capitalization.
- web-sdk/guides/ambient-implementation.mdx: H2s set to sentence-style (Controlled session management, Update encounter and ambient options, Next steps).
- mobile-sdk/ambient-guides/create-session.mdx: H2s set to sentence-style (What will you learn?, Create an ambient session, Provide clinical context…, Best practices, Next steps).
Last modified on March 23, 2026
