Style Guide

These conventions apply to every page in this site. The doc-update bot reads this file on every run to produce output consistent with human-authored pages. When in doubt, read an existing page in the same section before writing.

---

Tone

Write for engineers under time pressure, not for a general audience.

• Direct and present tense. "The worker fetches the job from the queue" not "The worker will fetch" or "The worker fetches (as of writing)."
• No marketing language. Never describe a component as "powerful", "robust", "seamless", or "cutting-edge."
• No filler openers. Do not start a page with "This document covers…" or "In this guide, you will learn…" — state the thing directly.
• Precise over polite. Say what is true. If something is a known limitation or a workaround, say so.

---

Headings

• H1 — one per page, matches title in frontmatter. Written by the author, not generated.
• H2 — major sections within the page. Use for top-level conceptual divisions.
• H3 — subsections within an H2. Use when an H2 has multiple distinct sub-topics.
• No H4 or deeper. If you need H4, the page probably needs to be split.

Headings describe what the section contains, not what the reader will do. "Authentication flow" not "Understanding the authentication flow."

---

Code blocks

Always use fenced code blocks with a language identifier. Never use indented code blocks.

```go
// correct

// wrong — no language identifier

Common identifiers used in this repo: `go`, `sql`, `yaml`, `json`, `bash`, `typescript`, `docker`.

Use the filename title extension when the file path adds context:

Inline code (backticks) is for identifiers, file paths, env var names, and short values only — not for prose emphasis.

---

Folder classification

The folder a page lives in is its type. If the content does not fit the type, move the page — do not bend the type to fit the content.

Folder	Question it answers	Example
reference/	What is this and how does it work?	Token Manager internals, database schema, API endpoints
how-to/	How do I do this specific task?	Add a REST endpoint, run LiveKit locally
runbooks/	What do I do right now during this incident?	Service is down, recording upload failed
adr/	Why was this decision made?	Why we migrated from MkDocs, why we abandoned Grafana Cloud
architecture/	How do the pieces fit together at a high level?	System overview, data flow diagrams
onboarding/	What does a new engineer need to know first?	Local setup, access checklist

Reference vs how-to is the most common confusion. Reference describes a system as it exists — it does not tell the reader what to do. How-to gives a sequence of steps to accomplish a goal — it does not explain why the system works the way it does. A page that mixes both should be split.

Runbooks vs how-to: runbooks are for incidents and time-sensitive recovery. A how-to is for planned development tasks. If the reader is stressed and the clock is running, it is a runbook.

---

Links

• Internal links: use relative paths. [Token Manager](../reference/backend/features/token-manager.md) not an absolute URL.
• External links: use absolute URLs. Open in the same tab — do not add target="_blank" in Markdown.
• Link text: describe the destination, not the action. "See Token Manager" not "Click here."
• Broken links: the Docusaurus build emits a warning for broken internal links. Fix them before merging.

---

Frontmatter

• The frontmatter block must be the very first thing in the file — no blank lines, no comments before it.
• last_verified and verified_by are set automatically on merge to main. Do not fill them by hand.
• description should be filled before opening a PR. An empty description degrades bot output quality.
• relates_to must be set accurately. A missing or wrong glob means the bot will not flag this page when the related code changes. Use [] only for pages with no direct codebase counterpart.

See Frontmatter Schema for field definitions and valid values.

---

Page structure

A well-structured page follows this order:

1. Frontmatter block
2. H1 title
3. One-paragraph summary (what this page covers — three sentences max)
4. Body sections (H2/H3)
5. Nothing else — no "see also" lists unless the links are genuinely non-obvious

Index pages (index.md inside a folder) describe what the section contains and link to sub-pages. They do not contain detailed reference content themselves.