# Documentation style guide (living)

This is the **living** home for documentation authoring conventions for the
RDBMS Playground website. It grows as we write.

- **Binding rules** come from
  [ADR-0042 §7](../docs/adr/0042-public-website-and-documentation-site.md);
  this guide must not contradict them. If a convention is significant,
  durable, or contested, it is decided in an **ADR** (new or amended), and
  this guide references it. Finer, settled conventions live here directly.
- **Open decisions** (not yet settled) are tracked at the bottom so we
  decide them deliberately rather than re-deciding per page. When one
  settles, move it up into the body (and to an ADR if it's significant).

Status tags used below: **[DECIDED]** (binding or settled) ·
**[OPEN]** (to be decided — see the log).

---

## Terminology & wording  [DECIDED — ADR-0042 §7]

- **No "DSL".** It is internal jargon. Use **simple mode** (the playground's
  keyword command language) and **advanced mode** (SQL).
- **No engine name.** Never name SQLite / STRICT / rusqlite / PRAGMA in
  user-facing copy. Say **"the database"** or **"the engine"**. (Continues
  the user-facing posture of ADR-0002.)
- Preferred terms (extend as we go): "command", "project", "table",
  "column", "relationship" (the user-facing word for a declared foreign-key
  link), "constraint", "index".
- Add new banned/preferred terms here as they come up, with a one-line
  reason.

## Voice & tone  [DECIDED, refine as needed]

- **Teaching-first.** Pedagogy wins ties (CLAUDE.md). Explain the *why*, not
  just the *how*; the audience spans beginners through learners ready for
  raw SQL.
- Second person ("you"), present tense. Imperative mood for step
  instructions ("Create a table…").
- Prefer short sentences and concrete examples over abstract prose.

## "Planned / not yet available" callouts  [DECIDED — ADR-0042 §7]

Any capability that is not yet fully implemented is **omitted** or carries a
clear **"planned / not yet available"** callout — never presented as
shipped. Use a Starlight aside (`:::caution` or a custom badge). **[OPEN]**:
exact component + wording (see log).

## Examples & code  [OPEN]

Direction (to confirm in the log):
- A single **standard example schema/dataset** reused across pages so
  readers build familiarity (candidate: a small, recognisable domain).
- Where both modes apply, show the **simple-mode** form and its
  **advanced-mode (SQL)** equivalent — the in-app teaching echo already
  pairs these, so docs can mirror it.
- Code blocks for input/output; reserve casts for motion/flow (see below).

## asciinema casts  [DECIDED, details OPEN]

- Casts show *flow/motion*; static code blocks show *exact input/output*.
  Prefer a code block when a still example suffices.
- Pair a hero/landing cast with a text transcript or the equivalent docs
  snippet (accessibility + SEO).
- Recorded via a scripted-input driver for paced, re-recordable sessions
  (ADR-0042 §2; recipe in `README.md`). **[OPEN]**: cast file naming,
  fixed terminal size, light/dark theme handling.

## Formatting  [DECIDED, refine]

- Starlight asides for notes/tips/cautions; tables for reference matrices
  (types, constraints, referential actions).
- Keyboard keys rendered consistently (e.g. <kbd>Ctrl</kbd>+<kbd>Z</kbd>).
- Cross-link related pages; never expose ADR numbers or internal jargon to
  the reader (ADRs are for us, not the docs audience).

---

## Open decisions log

Decide these as we write; record the outcome (and escalate to an ADR if
significant).

1. **Depth / organising spine.** Adopt **Diátaxis** (tutorial / how-to /
   reference / explanation) as the structure, or a lighter
   getting-started + reference + concepts split? Affects the whole sidebar.
2. **Page granularity & splitting.** One page per command, per
   command-family, or per task? When does a page split?
3. **Standard example schema/dataset.** What domain + tables do all examples
   share?
4. **Simple-vs-advanced pairing.** Always show both forms, or only where
   instructive? How to present the pairing visually.
5. **"Planned" callout component & wording.** Exact Starlight component and
   standard sentence.
6. **Reference generation vs hand-writing.** Generate the command reference
   from source (the `help` REGISTRY / `en-US.yaml`) to avoid drift, or
   author by hand? (Flagged in the plan's notes.)
7. **Versioning.** Do docs need version selectors at/after v1, or is
   single-version fine for launch?
8. **SEO/meta conventions.** Title/description patterns, Open Graph.