Files

T

claude@clouddev1 1fad29c0f9 docs: ADR-0042 — public website + documentation site plan

Planning artifacts for the first public website, recorded before any
code is written.

- ADR-0042: the decisions — Astro 5 + Starlight + Tailwind v4 (over
  SvelteKit); asciinema .cast demos reusable in docs (scripted-input
  driver, not history.log replay); in-page WASM playground deferred
  behind a stable demo seam, with the portable-core vs native-edge
  boundary recorded for a future ADR; portable static hosting (Vercel
  target); monorepo (website/); website is the canonical docs home;
  full-feature-set docs with "planned" callouts; user-facing copy uses
  no engine name and no "DSL"; install via prebuilt binaries + package
  managers.
- docs/plans/20260604-adr-0042-website.md: implementation plan with the
  grounded documentation inventory and phases A–E.
- website/STYLE.md: living documentation style guide + open-decisions log.
- docs/adr/README.md: index updated for ADR-0042 (numerical order).

2026-06-05 08:13:36 +00:00

4.5 KiB

Raw Blame History

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; 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. Ctrl+Z).
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).

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.
Page granularity & splitting. One page per command, per command-family, or per task? When does a page split?
Standard example schema/dataset. What domain + tables do all examples share?
Simple-vs-advanced pairing. Always show both forms, or only where instructive? How to present the pairing visually.
"Planned" callout component & wording. Exact Starlight component and standard sentence.
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.)
Versioning. Do docs need version selectors at/after v1, or is single-version fine for launch?
SEO/meta conventions. Title/description patterns, Open Graph.

4.5 KiB Raw Blame History