docs(website): document the seed command, with cast (ADR-0048)

New Reference page "Generating sample data" (captured output + a
two-table seed cast showing generation, FK sampling context, and a
`set` override); cross-links from inserting-and-editing-data and
columns; seed added to the rdbms highlight grammar;
querying/sql-queries renumbered. Cast stance in STYLE.md revised to
"justify the absence". Refs #33, #34.
This commit is contained in:
claude@clouddev1
2026-06-12 14:41:37 +00:00
parent 4691d7950a
commit 77c55fa669
9 changed files with 933 additions and 19 deletions
+22 -15
View File
@@ -138,23 +138,30 @@ a small standalone example, not by complicating this schema.
- Pair a hero/landing cast with a text transcript or the equivalent docs
snippet (accessibility + SEO).
### Where to use a cast [DECIDED 2026-06-10]
### Where to use a cast [DECIDED 2026-06-10; stance revised 2026-06-12]
**Rule: a cast wherever the app *does something*.** A cast at the top of a page
gives the reader the *shape* of what the page describes — quickly and visually
— with the detailed text below for when they need it. (This helps visual
learners, but is valuable more broadly.) Concretely:
**Default to a cast; justify its _absence_, not its presence.** A cast at the
top of a page gives the reader the *shape* of what the page describes —
quickly and visually — with the detailed text below for when they need it. It
earns its place two ways, both observed in real use: it helps **visual
learners** grasp a flow at a glance, and it gives **advanced learners a fast
entry point and overview** — skim the motion, then drop into the prose only
where needed. So the question for each page is not "does this deserve a cast?"
but "is there a good reason *not* to have one?"
- **Broadly** on the pages about *doing / interacting*: the landing, **Getting
started** (first project, modes), **Using the playground** (the assistive
editor, output-pane scrolling, undo/redo, projects, copy, export/import), and
**Guides**.
- **Selectively** on **Reference** — only where motion beats the still (e.g.
the relationship diagram being drawn; a query plan appearing). Reference
pages keep their **captured static output** regardless; a cast complements,
never replaces it.
- **Skip** pure-lookup / conceptual pages with nothing to animate (e.g. the
Types table, prose Concepts pages).
This is **not** a mandate for a cast on every page, still less several per
page: a page wants a cast only where the app *does something* worth seeing, and
one well-chosen cast is almost always enough. Concretely:
- **Expect a cast** on any page where the app *does or shows* something: the
landing, **Getting started**, **Using the playground**, **Guides**, and the
**Reference** command pages (a command being run, a diagram drawn, a query
plan or a table of generated rows appearing).
- **Justify the absence** on the rest — pure-lookup or conceptual pages with
nothing to animate (e.g. the Types table, prose Concepts pages). "Nothing
moves here" is a fine reason to record on; "I didn't think about it" is not.
- Reference pages keep their **captured static output** regardless; a cast
complements it, never replaces it.
- A cast is **selective**: it shows a chosen, representative slice of what the
page documents — it need not exercise every command on the page.
- **Autoplay only the landing hero**; elsewhere casts are click-to-play (a