Documentation style spec
v0.1 · The single, operational spec for how Gridshift docs are written and
structured. It governs everything under docs/ (Mintlify). Voice and brand rules
live in BRAND.md (repo root) — this file is the docs-specific
operationalization of them, and the checklist the /docs-audit skill enforces.
If a rule here and BRAND.md ever disagree, BRAND.md wins on voice; this file
wins on structure and Mintlify usage.
1. Voice, in one paragraph
Docs are the literal end of register by altitude — no marketing,
ever. Write to a producer who is technical and impatient with fluff. Present
tense, imperative for actions (“Press ⌘U”, not “You can press ⌘U”). US
English (color, behavior, optimize, canceling, gray). Bold a domain term
once, on first use, then plain. Cut the first sentence if it’s throat-clearing.
No exclamation marks, no emoji.
2. Page anatomy
Every feature page follows the same spine:
- Frontmatter (see §3).
- One-sentence definition — opens the page, bolds the key term once.
Quantize snaps the start of notes and audio transients to the nearest grid position.
- How it works — the mental model, briefly. Why it behaves as it does.
- Task sections — one per thing the user does, task-oriented sentence-case
headings (“Quantize a selection,” not “Quantization”). Steps inside.
- Shortcuts — a table, when the feature has them.
- Related / caveats — cross-links and edge cases, via callouts.
Concept pages (concepts.mdx, introduction.mdx) explain the model and may skip
the task sections. Shortcut-reference pages are primarily tables.
Headings: sentence case, task-oriented, verb-first where it’s an action. Never
Title Case a heading (feature names inside prose stay Title Case — they’re proper
nouns; see §6).
3. Frontmatter
reviewed is the freshness signal — it means last checked for accuracy, which
is what predicts staleness. It is not an edit date: git already records edits,
and Mintlify shows a git-based “last updated” (metadata.timestamp). Never hand-set
reviewed — a date no audit produced is a claim no one checked.
4. Components — when to use which
Use the smallest thing that does the job. A sentence beats a callout; a callout
beats a section. Never stack callouts, never decorate.
<Steps> and <Warning> are sanctioned but not yet used across the docs — introduce
them where they fit; don’t retrofit mechanically.
5. Conventions
- Shortcuts: real glyphs in inline code, no
+: `⌘U`, `⌥A`,
`⇧⌘D`. Modifier order: ⌃ ⌥ ⇧ ⌘.
- Command Palette paths:
Command Palette → **Set Record Quantize** — bold the
command name.
- Feature names: exact canonical casing from the BRAND.md glossary.
Never lowercase or hyphenate a variant. Platform names keep their casing: MIDI,
iOS, iCloud, macOS, MCP.
- Cross-links: relative, by canonical name —
[Groove & Swing](/features/groove).
- Numbers & units: numerals for measured values, space before the unit —
48 kHz, 256 frames, 5 ms.
- Defaults: always state the current default, and mark it —
**None** (default).
6. Accuracy contract
This is what makes a doc correct, not just well-formed. Every one of these is a
checkable claim and must match the current code:
- Keyboard shortcuts and modifier combos.
- Default values and the set of available options / modes / enum cases.
- Parameter, control, and setting names (as shown in the UI).
- Command Palette command names and menu paths.
- File locations, formats, and limits stated as fact.
- Stated behavior that the code actually implements.
When a claim can’t be verified from code (subjective/behavioral prose), it is
flagged for human review, not silently rewritten.
7. Definition of done
A page passes audit when all of these hold:
Last modified on August 1, 2026
