​

Suki documentation writing style guide

• Structure and process: File layout, navigation, release note format, build commands → AGENTS.md
• Mintlify components: Callouts, Steps, Tabs, code blocks, API components → .cursor/rules.mdx

​

Voice and tone

• Overall: Crisp, clear, and professional. We write for healthcare developers and technical readers who need accurate, scannable information.
• Brevity: Use fewer words. Lead with the main idea; prune excess. Give enough to decide or act, not more.
• Front-load: Put the most important information and keywords at the start of sentences and headings so content is scannable.
• Healthcare context: Follow healthcare and medical terminology standards. Keep a professional, clinical tone appropriate for healthcare developers; avoid casual or marketing language in technical docs.
• Instructions: Use second person (“you”) for procedures and how-to content. Use present tense for current state and future tense for outcomes.

​

Punctuation

• No em dashes: Do not use em dashes (—). Use commas, colons, or semicolons instead.
• Spaces around dashes: When using a hyphen or en dash, do not add spaces around it (e.g. “key-value pair,” not “key - value pair”).
• Oxford comma: In a list of three or more items, include a comma before the conjunction (e.g. “Android, iOS, and Windows”).
• One space: Use one space after periods, question marks, and colons.
• Headings and short list items: Omit periods at the end of page titles, headings, subheadings, and list items that are three or fewer words. Use periods in body paragraphs and longer list items.

​

Capitalization

• Headings and UI: Use sentence-style capitalization. Capitalize the first word and proper nouns only (e.g. “Get started with the Web SDK,” not “Get Started With the Web SDK”). Do not use title case for headings. This aligns with Google’s developer documentation style for titles and headings.
• Page title and sidebar title: Use title case for frontmatter title and sidebarTitle on every page so navigation and page headers are consistent across the doc.
• Apply sentence case to: Headings (H2, H3), link text, table headers and cell labels, and list items.
• Buttons and button-like UI: Use title case for button labels and button-like elements in the docs to match product design. This includes: <Card title="...">, <Step title="...">, <Tab title="...">, <Accordion title="...">, and CTA/link text that is styled as a button (e.g. “Start Building”). Do not use sentence case for these.
• Product and feature names: Follow official product naming (e.g. “Web SDK,” “Ambient Session,” “Problem-Based Charting”). Do not change product names to sentence case.

​

Strong writing

• Start with verbs where possible: Prefer “Store files online and share them with coworkers” over “You can store files online and you can share them with coworkers.”
• Avoid weak openings: Edit out unnecessary “You can” and “There is/are/was/were” when a more direct phrasing works.
• Active voice: Prefer active voice unless the actor is unknown or passive is clearer.
• Parallel structure: Use parallel structure in lists, headings, and procedures (e.g. all items start with a verb or all with a noun).

​

Contractions

• Use contractions for a natural, readable tone (e.g. “it’s,” “you’ll,” “we’re,” “don’t”). Avoid them only in highly formal or compliance-focused content where the team has agreed to avoid them.

​

Scannable content

• Headings: Use clear, descriptive headings that reflect the content. Structure with H2 for main sections and H3 for subsections. Prefer task-based headings with a bare infinitive (e.g. “Create a session”) or noun phrases for conceptual sections (e.g. “Migration to the Web SDK”).
• Lists: Use bulleted or numbered lists for steps, options, or three or more related items. Keep list items parallel in structure where possible.
• Short paragraphs: Prefer short paragraphs (two to four sentences) for easier scanning.
• Progressive disclosure: Put basic concepts before advanced ones; break complex procedures into numbered steps and include prerequisites before instructions.

​

Documentation workflow

1. Plan: Create a todo list (e.g. review content, check links, verify examples, update dates).
2. Apply style: Check headings (sentence case), punctuation (no em dashes, Oxford comma), and tone (professional, developer-focused).
3. Verify: Ensure link text is sentence case; fix any title case in frontmatter, tables, or <Step title="..."> values.

​

Bias-free and inclusive language

• Gender-neutral: Use gender-neutral terms (e.g. “chair” or “moderator,” not “chairman”; “workforce” or “staff,” not “manpower”). Do not use “he,” “she,” or “he/she” for generic references; use “you,” “they,” “the user,” or rewrite to plural.
• People-first language: When referring to disability, focus on the person first (e.g. “users who are blind or have low vision,” “customers with limited dexterity”). Do not use pity language (“suffering from,” “stricken with”). Mention disability only when relevant.
• Avoid problematic terms: Do not use terms that imply hierarchy or bias (e.g. use “primary/subordinate” instead of “master/slave,” “perimeter network” instead of “DMZ” where that convention is used). Avoid slang that could be culturally appropriative or derogatory.
• Examples and scenarios: Use diverse, inclusive examples and names. Avoid stereotypes in roles or scenarios.

​

Global and translatability

• Plain language: Use clear, simple wording so content is easier to translate and understand for readers whose first language is not English.
• Consistent terminology: Use the same terms for the same concepts across the docs. Link to the Glossary for definitions. Avoid synonyms for the same concept in one doc.
• Locale-neutral examples: When using place names or regions in examples, avoid politically disputed areas. Prefer generic or varied examples when possible.

​

Terminology and healthcare

• Healthcare/medical terms: Follow standard healthcare and medical terminology. When in doubt, align with common clinical and developer usage (e.g. LOINC, ICD-10, encounter, ambient session).
• Suki-specific terms: Use product terms consistently (e.g. “ambient session,” “Problem-Based Charting,” “PBC”). Define or link to the Glossary on first use in a doc when helpful.
• API and SDK terms: Match the names used in the API, SDK, and UI (e.g. ambientOptions, setEncounter).

​

Technical structure (summary)

• Frontmatter: Every doc page must have title and description in YAML frontmatter. Use sentence case for title and sidebarTitle.
• Steps and UI strings: Use sentence case for <Step title="...">, <Tab title="...">, <Accordion title="...">, and table headers.
• Images: Use light/dark variants with className="block dark:hidden" and className="hidden dark:block" where appropriate.
• For full Mintlify component usage and examples, see .cursor/rules.mdx. For release note format and navigation, see AGENTS.md.

​

Further reading

• Google developer documentation style – Capitalization, headings
• Microsoft Writing Style Guide – Voice, Top 10 tips, bias-free communication, global communications