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:
+22
-15
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user