Documentation Index

Fetch the complete documentation index at: https://developer.suki.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Suki documentation writing style guide

This guide is the single source of truth for writing style and terminology for Suki developer documentation (APIs, SDKs, guides, release notes, and UI copy on this site). It aligns with the Suki technical writing style guide (V.1.2) and adds rules specific to this Mintlify repo. Audience: Developers integrating with the Suki Platform. Documentation should be as clear and dependable as the product: professional, precise, and easy to scan. Where to find what:

• Structure, navigation, release notes, build commands: AGENTS.md
• Mintlify components: Callouts, Steps, Tabs, code blocks, API components → .cursor/rules.mdx

---

​

Documentation guiding principles

---

​

Voice and tone

Suki’s voice is professional, helpful, and precise. Healthcare and AI require trust; the tone is straightforward and conversational, like a knowledgeable colleague—not stiff marketing copy and not slang. Characteristics Repo-specific tone rules

• Avoid weak hedges for outcomes or requirements: do not rely on “may help,” “may find,” “may require,” “may need,” “might,” or “could” when you can state the fact or condition directly.
• Front-load: Put the most important information at the start of sentences.
• Healthcare context: Use standard clinical and developer terminology where it fits; keep a professional, clinical tone. Avoid hype and empty superlatives.
• Instructions: Use second person (“you”) for procedures. Prefer present tense for how the product behaves (When you call this method, it sends the note to the EHR), not future tense (it will send) unless you describe a future release.

---

​

Writing style and grammar

• Active voice: The getPatient endpoint returns the patient’s demographic data. Not: The patient’s demographic data is returned by the getPatient endpoint.
• Address the reader: Before you begin, generate an API key from the developer console. Not: An API key must be generated from the developer console before a developer can begin.
• Strong openings: Prefer verbs and direct statements. Cut filler such as “You can…” and “There is/are…” when the sentence still works without them.
• Parallel structure: In lists and headings, keep items parallel (all start with a verb, or all with a noun phrase).
• Contractions: Use them for a natural tone (it’s, you’ll, don’t) unless the page is compliance-focused and the team agreed to avoid them.

---

​

Punctuation

• No em dashes (—) on this site: Do not use em dashes. Use commas, colons, or parentheses instead. (This repo policy overrides the corporate guide’s optional em-dash usage.)
• En dash (–) for ranges: Use an en dash without spaces around it for numeric or date ranges (2023–2024, lines 15–20). Hyphenate compound modifiers per standard English (key-value pair, not key - value pair).
• Oxford comma: In a series of three or more items, use a comma before the conjunction (note ID, status, and timestamp).
• Ampersands: Do not use & in prose unless it is part of a proper name or required in code (AT&T, query strings). Write and.
• One space after periods, question marks, and colons.
• Headings and very short list items: No period at the end of page titles, headings, subheadings, or list items of three or fewer words. Use periods in body paragraphs and longer list items.

---

​

Capitalization

• Headings (H2, H3) and link text: Sentence case—capitalize the first word and proper nouns only. Get started with the Web SDK; Authenticate your API requests. Aligns with Google’s developer documentation style (capitalization in headings).
• Frontmatter title and sidebarTitle: Use sentence case for doc titles and sidebar labels (Notification settings, not Notification Settings), unless product naming requires an exception.
• UI labels in running text: Match the exact capitalization of the product UI. Bold the label when you refer to it (Click Save).
• Official product and feature names: Use Suki’s official names (Web SDK, Ambient Session, Problem-Based Charting, Suki Platform). Do not force sentence case on trademarked or branded names.
• Buttons, cards, steps, tabs, accordions: Mintlify title props and button-style CTAs use title case to match the product (Start Building, Create Session). See .cursor/rules.mdx.
• Table headers and cell labels: Sentence case unless they echo exact UI strings.

---

​

Terminology

Use consistent, official names. On first mention in a major section, prefer the full form; shorten only when the reader cannot confuse it with something else. Link to the Glossary when a term is defined there. Avoid swapping synonyms for the same concept within one page.

---

​

Formatting and structure

​

Headings

Use Markdown hierarchy (#, ##, ###) for structure. Prefer task-style H2/H3 (Create a session, Configure authentication) or clear noun phrases for concepts (Migration to the Web SDK).

​

Lists

• Bulleted lists: Unordered items; introduce with a complete sentence ending in a colon.
• Numbered lists: Sequential steps; introduce with a complete sentence; start each step with an imperative (Click, Run, Add).

​

Admonitions (Mintlify)

Use callouts sparingly. Map intent to Mintlify components per .cursor/rules.mdx: If corporate copy refers to an Important callout, use Warning or Note here depending on severity.

​

Code

• Inline: Backticks for identifiers (createNote), parameters (patientId), filenames (config.json), and literal values when needed.
• Blocks: Fenced code with a language tag; prefer realistic, runnable examples and comments where they help. For Mermaid on this site, use the patterns in AGENTS.md (e.g. actions={false} where print/PDF matters).

---

​

Documenting APIs, SDKs, and errors

API endpoint pages should follow a logical order where the template allows: title (method + path), short description, parameters (table), request body, responses (status + examples), then client examples (cURL, JavaScript, Swift, etc.). Errors: Document in a scannable way: For SDK reference grouped options and ResponseField usage on this site, follow SDK reference pages and ResponseField.

---

​

User interface (UI) in documentation

When you describe the developer console or other UIs:

• UI labels: Bold; spelling and capitalization must match the product (Click Save; In the navigation menu, select API Settings).
• User-entered values: Bold (Enter My First Suki App in the Project name field).
• Actions: Imperative mood (Click Create key, Select the Read-only checkbox). Not: The Create key button should be clicked.

---

​

Accessibility and media

• Alt text: Describe content and purpose, not “screenshot” or “image.” Good: Developer console dashboard showing API usage for the last 30 days.
• Link text: Describe the destination (for example, Getting started as the link text for that guide). Avoid click here and bare URLs as link text.
• Plain language: Short sentences and familiar words help every reader, including non-native English speakers.
• Screenshots: Crop to what matters; annotate simply; no real PHI—use placeholders; refresh when the UI changes materially.
• Diagrams: Prefer simple, labeled flows; Mermaid is fine when it follows site print/PDF rules (AGENTS.md).

---

​

Content types (orientation)

---

​

Updates, changelogs, and versioning

• Release notes and RSS: Follow AGENTS.md (monthly pages, LATEST badge, RSS <Update> blocks).
• Changelog entries: Prefer version/date, change type (Added, Changed, Deprecated, Removed, Fixed), short description, and a link to the relevant doc.
• In-page labels (when used): [New], [Updated], [Deprecated] in bold brackets for significant visibility; pair deprecation with a Warning and migration pointer.
• Versioned doc sets: When the product ships multiple major doc versions, surface version choice in the site UI; default to latest; keep older versions reachable for integrators on prior releases.

Workflow for edits on this repo: Plan → apply this guide → verify links, examples, and dates → PR review. Technical accuracy is owned with Engineering/PM; style and consistency with peer review as your process defines.

---

​

Bias-free and inclusive language

• Gender-neutral terms (chair, workforce); use you, they, or plural—not he/she.
• Disability: People-first when relevant (users who are blind or have low vision). No pity framing (suffering from). Mention disability only when it matters to the task.
• Avoid biased or outdated terms (primary/subordinate not master/slave where that metaphor appears; prefer neutral infrastructure terms).
• Examples: Varied, inclusive names and roles; avoid stereotypes.

---

​

Global and translatability

• Plain, locale-neutral examples where possible; avoid politically disputed place names as stand-ins.
• Consistent vocabulary across the site; link the Glossary instead of inventing new synonyms.

---

​

Terminology and healthcare

• Clinical and standards terms: Use common healthcare developer usage (LOINC, ICD-10, encounter, ambient session) consistently with the rest of the site.
• Suki products: Ambient session, Problem-Based Charting (PBC), etc., as in product naming—do not contradict AGENTS.md product boundaries (Headless Web SDK vs Dictation SDK).

---

​

SDK reference pages and ResponseField

Match guide voice: direct, scannable, task-aware.

• Section intro: One purposeful line that sets up the group (not The following options are available).
• ResponseField: Clear definition; use required on the component when mandatory; optional fields may use Optional: in the body when consistent with sibling pages (see Authentication hook).
• Gaps vs npm: Anchor copy in on-site examples and link to Quickstart or canonical pages rather than vague see README unless the team standardizes that elsewhere.
• Headings: Concrete (Configuration, Import) over vague (What it does).

---

​

Technical structure (summary)

• Frontmatter: title and description on every MDX page.
• Mintlify Step / Tab / Accordion titles: Sentence case for doc-style titles; title case when the string is a product button or card title (see Capitalization).
• Images: Light/dark variants with className="block dark:hidden" and className="hidden dark:block" when both exist.

Full component syntax: .cursor/rules.mdx. Navigation and PDF behavior: AGENTS.md.

---

​

Further reading

• Google developer documentation style — Capitalization, headings
• Microsoft Writing Style Guide — Voice, bias-free communication, global communications