Skip to content

Documentation Style Guide

Status: Current | Last reviewed: 2026-05-28

Every doc under docs/ follows the rules on this page. Per-app READMEs and root entry points (README.md, CLAUDE.md, AGENTS.md, .devcontainer/CLAUDE.md) follow them too. If a rule conflicts with making a doc clear, prefer clarity and note the deviation at the top.

Voice

Write in second person, present tense, declarative.

  • Yes: "You run wake-up.sh. The script starts Overmind."
  • No: "We recommend running wake-up.sh, which will start Overmind."
  • No: "The user should run wake-up.sh."

Do not use first person plural ("we", "our", "let's"). Address the reader directly. Skip throat-clearing ("In this document, we will…"). Lead with the answer.

Length

One topic per file. Hard cap of about 400 lines. If you cross that, split.

The first paragraph after the H1 has to tell the reader what the doc covers and when to read it. If it does not, rewrite it.

Headings

  • H1: title only, once per doc.
  • H2: top-level sections.
  • H3: subsections.
  • H4 or deeper: only inside reference tables that demand it. Avoid otherwise.

No emoji in headings. No trailing punctuation. Sentence case ("Cloud-managed swap paths"), not Title Case.

Code blocks

Always tag the language. Common choices: bash, sql, python, typescript, tsx, go, yaml, json, dockerfile, nginx, text.

Bash blocks contain runnable commands with no leading $. Reserve $ for when you need to show interactive prompt and response together.

Yes:

overmind restart ai-orchestrator

No:

$ overmind restart ai-orchestrator

For multi-step recipes, comment with # rather than narrating between blocks.

File and code references

Use markdown links with relative paths from the repo root, not bare paths in prose. Linkable file references are clickable in the IDE and in the rendered docs.

  • Yes: See [universal_builder.py](../../apps/ai-orchestrator/lib/pipecat/pipeline/builders/universal_builder.py).
  • No: "See apps/ai-orchestrator/lib/pipecat/pipeline/builders/universal_builder.py."

For line ranges, use #L42-L58.

Function and class names go in backticks: resolve_agent_version(), PhoenixInstrumentedOpenAIRealtimeLLMService. Env vars too: MASTER_ENCRYPTION_KEY.

Tables

Use tables for any matrix-shaped data: ports, env vars, integrations, status grids, swap mappings. Do not use prose to describe rows of comparable items.

Keep tables narrow. If a column needs more than ~80 characters, break it into a subsection beneath the table.

Callouts

Two callouts only. Both use blockquote syntax.

> Note: Information that is true but easy to miss.

> Warning: Action that loses data, breaks production, or wastes hours.

No emoji callouts. No [!NOTE] GitHub admonitions; they do not render outside GitHub.

Status banner

Every doc starts with this line directly under the H1:

Status: Current | Last reviewed: 2026-05-28

Status values:

  • Current — accurate as of the review date.
  • Draft — work in progress, not yet reviewed.
  • Stale — known to be out of date; replace or archive.
  • Archived — kept for reference only; do not act on it.

When you change a doc, update the review date.

Every doc ends with a "See also" section linking 2–4 related docs. The link list is what makes the handbook navigable, not the master index.

## See also

- [Universal pipeline builder](../04-processes/universal-pipeline-builder.md)
- [SQL functions](../06-schema/sql-functions.md)

Diagrams

Mermaid only. Save the source as .mmd next to the doc that uses it, and embed via fenced ```mermaid blocks. Do not commit raster images of architecture diagrams — they go stale and cannot be diffed.

Terminology

Use the canonical terms from glossary.md. The most common ones:

  • Vanguard — the dev devcontainer (Codespaces or EC2). Not a remote cluster.
  • Sentinel — the production GKE cluster TrueServe operates.
  • Cloud customer environment — a customer-operated EKS / AKS / on-prem cluster.
  • agent vs agent_version — identity vs runtime config. Always distinguish.
  • surface — the end-user UI (apps/surface-app), distinct from surface_configs (DB row that styles it).
  • A2UI — agent-to-UI rendering protocol. Always uppercase.
  • MCP — Model Context Protocol. Always uppercase.
  • BYOC / BYOVA / BYOT — bring-your-own-carrier / -virtual-agent / -telephony.

When introducing one of these for the first time in a doc, link to the glossary entry.

What not to write

  • Do not narrate intent ("We will now configure…"). Configure it.
  • Do not write changelogs inside docs. Use git history.
  • Do not duplicate content from another doc — link instead.
  • Do not write FAQ sections. Promote each Q to its own H2 in the right doc.
  • Do not write "About this document" preambles. The first paragraph already does that work.

See also