Skip to main content

​
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:
  1. Frontmatter (see §3).
  2. 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.
  3. How it works — the mental model, briefly. Why it behaves as it does.
  4. Task sections — one per thing the user does, task-oriented sentence-case headings (“Quantize a selection,” not “Quantization”). Steps inside.
  5. Shortcuts — a table, when the feature has them.
  6. 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

KeyRequiredRule
titleyesThe feature’s canonical name (§6). Title Case for the proper noun.
descriptionyesOne sentence, sentence case, no trailing period-stuffing. This is the search-result line and the SEO description — make it say what the feature does.
sidebarTitlerecommendedShort form for the nav when title is long.
iconrecommendedA Lucide icon name, consistent with sibling pages in the group.
reviewedmanagedISO date the page was last verified against the code (§6). Written by /docs-audit; don’t backfill by hand. Missing = never verified.
verifiedAgainstoptionalApp/build version the page was checked against, alongside reviewed.
---
title: "Quantize"
sidebarTitle: "Quantize"
description: "Snap notes and audio transients to the grid, by a chosen amount."
icon: "grid"
reviewed: 2026-07-11
---
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.
ElementUse it forDon’t
<Steps> / <Step>Any procedure of 2+ ordered actions. Prefer over a bare numbered list — it renders the sequence clearly.Single actions (just write the sentence).
<Note>A caveat or aside that qualifies the main text.General prose that belongs in the body.
<Tip>A power-move, shortcut, or workflow accelerator.Restating a step.
<Info>A prerequisite or piece of background context.Warnings — use <Warning>.
<Warning>Reserved for data loss or irreversible actions only.Ordinary caveats (that’s <Note>).
<Frame>Wrapping a screenshot or image, with a caption.Text. Every product image lives in a <Frame>.
<Card> / <CardGroup>Navigation / overview grids (e.g. a feature index).Inline emphasis inside a page body.
TablesSetting × behavior, mode × behavior, shortcut × action.Prose that isn’t really tabular.
`inline code`Shortcuts (with glyphs), parameter names, values, file/menu paths.Emphasis (use bold).
<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:
  • Frontmatter has title + description; description is one sentence, sentence case, US English.
  • Opens with a one-sentence definition; key term bolded once.
  • Headings are sentence case and task-oriented.
  • Procedures use <Steps>; callouts follow §4; no stacked/decorative callouts.
  • Shortcuts use glyphs in inline code; feature names match the glossary; US English throughout.
  • Every checkable claim (§6) matches current code, or is flagged for review.
  • Length fits the content — a feature page is typically ~40–100 lines. No padding.
  • Cross-links resolve and use canonical names.
Last modified on July 11, 2026