Voice & Writing

Documentation is a product surface, and the writing in it carries Cheetah's voice as much as the visual design does. This page is the working reference for how to write docs that sound like Cheetah.

Voice

Cheetah's documentation voice is:

Direct. Lead with the load-bearing sentence. Don't open paragraphs with "It's worth noting that..." or "It should be mentioned that..." — if it's worth mentioning, mention it.

Technically literate. We write for engineers who already understand robotics, REST APIs, and either Python or TypeScript. We don't define what an HTTP request is. We don't explain what semantic versioning means before talking about versioning. When we do introduce a new concept, we link to the definition once and move on.

Honest about alpha. Cheetah is in alpha. When we know something is going to change, we say so. When we know an API surface is wrong, we don't write reference docs that pretend it's settled. The versioning policy is the model for this — read it for examples of the tone.

Not marketing-adjacent. Docs are not the place to sell Cheetah. No "powerful," no "seamless," no "robust." If a feature is genuinely powerful, demonstrate it; don't claim it.

Confident without being clever. Avoid jokes, puns, and footnote-style humor. The docs are an instrument, not a personality. The visual chrome carries the personality — the writing should be plain.

Tone by audience

Audience	Where	Tone
Stakeholders / evaluators	/applications/*/overview	Clear, value-oriented, free of internal jargon. Closer to product marketing but still factual.
End users / operators	/applications/*/user-guide	Procedural. Step-by-step. Lots of screenshots when they exist.
Developers / integrators	/developers/*	Technical. Reference-grade. Assume competence.
AI agents	/agents.md, /llms.txt	Structured. Imperative. Optimized for tool use.

The same fact may need to be expressed differently for each audience. That's expected, not redundant.

Formatting conventions

Headings

• Use sentence case, not Title Case. "Webhook event payload versioning" not "Webhook Event Payload Versioning."
• H1 is the page title (auto-rendered from frontmatter title).
• H2s are major sections; the renderer auto-adds the top divider rule.
• H3s are subsections; no divider.
• H4 should be rare — it renders as a HUD-style label. Use for callouts within a long subsection.

Lists

Unordered lists render with a › glyph in cheetah-teal. Ordered lists render with monospace zero-padded numerals (01, 02, 03) in cheetah-pink. Choose the one that fits the content, not the visual.

Code samples

• Triple-fenced with a language tag — always specify the language.
• Pin versions where applicable. Don't write pip install cheetah-client — write pip install "cheetah-client @ git+...@v0.0.129...".
• Prefer complete, runnable snippets over fragments. AI tools (and humans) will copy and run what you write.
• For SDK examples, show both Python and TypeScript when both exist.

Tables

Use tables for things that are genuinely tabular: API endpoints, error codes, configuration keys. Don't use tables to make a bullet list look fancier.

Links

• Use the full path: /developers/versioning, not versioning.
• Don't write "click here" or "this link" — describe what's at the other end. "See the versioning policy for the deprecation timeline."
• Internal links don't get a trailing colon or em-dash explainer in the middle of prose.

Emphasis

• Bold for genuinely load-bearing words. Use sparingly — if every sentence has a bold word, none of them stand out.
• Italic for inline emphasis when bold is too loud, or for cross-references to a glossary term on first mention.
• Don't use code formatting for emphasis of non-code text.

Frontmatter reference

Every page requires this frontmatter at the top:

---
title: Page Title
description: One-line description, used in <meta> and AI summaries.
section: developers
status: stub | alpha | beta | stable
---

Optional fields:

last_verified: 2026-05-24       # auto-updated by build; can be set manually
applies_to:                     # rendered as the "APPLIES TO" banner
  cheetah_service: ">=0.0.129"
  schema_version: 2

status values

Value	Meaning	Rendered as
stub	Placeholder, content coming soon	Pink "STUB" badge in page header + sidebar
alpha	Real content but the underlying feature is alpha	Pink "ALPHA" badge
beta	Feature is in beta	Teal "BETA" badge (planned)
stable	Production-ready	No badge

Writing patterns by page type

Reference pages (/developers/api-reference, /developers/errors)

Reference is facts. Short. Scannable. No prose introduction needed. Lead with a table or a definition list. Examples come last, not first.

Tutorial pages (/quickstart, /developers/quickstart)

Tutorials walk a reader from start to a working result. Number the steps explicitly (ordered list — they render with the monospace numerals which feel correct for a stepwise procedure). End every tutorial with "where to go next" — three links, no more.

How-to pages (/developers/integrate/*)

How-tos solve one specific problem for someone who already has context. Lead with the problem statement. Don't recap the platform. Don't define terms — link to the concept page if needed.

Explanation pages (/concepts/*)

These are the long-form pages. They have room to breathe. Use diagrams (we'll standardize on a tool for these — for now, ASCII or embedded images). Connect concepts to each other liberally.

Stakeholder overview pages (/applications/*/overview)

Different voice from the rest of the docs. More marketing-adjacent. Use the same chrome (viewfinder frames, status strips) but soften the technical density. Screenshots matter here more than anywhere else.

A note on AI-readability

Clients will pipe these docs into AI tools to build integrations. Write with that in mind:

• Self-contained code samples. Don't reference state from elsewhere on the page ("session_id from above"). Re-establish context in every fenced block.
• Don't bury critical info in images. A pinout diagram is fine, but always include a textual table next to it. An LED color chart must have text equivalents.
• No "see above." AI tools chunk pages; "above" may not be in scope.
• Stable IDs on headings. The renderer adds these automatically based on heading text — don't change heading text casually because it breaks deep links.

If you're about to write something where you find yourself thinking "the reader will figure it out from context," assume they won't and the AI definitely won't.