docs: website docs structure + first content pages
Phase D foundation. Configures the pragmatic four-section sidebar (Getting started / Guides / Reference / Concepts) and replaces the template example pages with grounded content built on the shared "library" example database (authors/books/members/loans): - Getting started: installation, first project, simple vs advanced, the example library. - Reference: Types (all ten + serial/shortid + advanced aliases), Tables (create/drop, compound PK, advanced CREATE TABLE). - Concepts: projects & storage (readable files, derived database, autosave, temp projects). - Guides: Build the library (draft, to be refined for teaching). Command syntax grounded in en-US.yaml usage/help, command.rs, and types.rs (verified against tests). Records the settled doc decisions in STYLE.md. Build green (10 pages, Pagefind); content clean of "DSL"/engine-name.
This commit is contained in:
claude@clouddev1
+70
-26
@@ -39,22 +39,63 @@ Status tags used below: **[DECIDED]** (binding or settled) ·
|
||||
instructions ("Create a table…").
|
||||
- Prefer short sentences and concrete examples over abstract prose.
|
||||
|
||||
## Structure [DECIDED]
|
||||
|
||||
Pragmatic, Diátaxis-influenced split (four top-level sidebar sections,
|
||||
autogenerated per directory under `src/content/docs/`):
|
||||
|
||||
- **Getting started** — install, first project, simple vs. advanced, the
|
||||
example database.
|
||||
- **Guides** — task-oriented how-tos. *These are the most important didactic
|
||||
content and will be iterated for teaching quality before publication.*
|
||||
- **Reference** — the exhaustive command/SQL/type surface. **Page
|
||||
granularity: one page per topic / command-family** (Tables, Columns,
|
||||
Relationships, Indexes, Constraints, Inserting & editing data, Querying,
|
||||
Types, …), each covering the simple-mode and advanced-mode forms where
|
||||
both apply. Hand-written now (the command surface is settled bar H1a
|
||||
output); small post-release adjustments are expected and fine.
|
||||
- **Concepts** — the "why": projects & storage, undo & history, etc.
|
||||
|
||||
Ground every reference page in source — `parse.usage.*` and `help.*` in
|
||||
`src/friendly/strings/en-US.yaml`, `src/dsl/command.rs`, `src/dsl/types.rs`
|
||||
— never paraphrase grammar from memory.
|
||||
|
||||
## "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).
|
||||
clear callout — never presented as shipped. Standard form: a Starlight aside
|
||||
|
||||
## Examples & code [OPEN]
|
||||
```md
|
||||
:::caution[Planned]
|
||||
This is planned and not yet available.
|
||||
:::
|
||||
```
|
||||
|
||||
Direction (to confirm in the log):
|
||||
- A single **standard example schema/dataset** reused across pages so
|
||||
readers build familiarity (candidate: a small, recognisable domain).
|
||||
## Examples & code [DECIDED]
|
||||
|
||||
- **Shared example database: a small library** — `authors`, `books`,
|
||||
`members`, `loans` (see the canonical schema below). Reuse it across all
|
||||
pages so readers build familiarity; it models 1:n (an author has many
|
||||
books) and m:n (books ↔ members, through loans).
|
||||
- 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).
|
||||
pairs these, so docs mirror it.
|
||||
- Code blocks for exact input/output; reserve casts for motion/flow.
|
||||
|
||||
### Canonical library schema (source of truth for examples)
|
||||
|
||||
Use these exact names/types in every example:
|
||||
|
||||
| Table | Columns (playground types) |
|
||||
|-----------|---------------------------------------------------------------------------------------------|
|
||||
| `authors` | `author_id` serial (pk) · `name` text (not null) · `birth_year` int |
|
||||
| `books` | `book_id` serial (pk) · `title` text (not null) · `author_id` int (→ authors) · `published` int · `isbn` text (unique) |
|
||||
| `members` | `member_id` serial (pk) · `name` text (not null) · `joined` date |
|
||||
| `loans` | `loan_id` serial (pk) · `book_id` int (→ books) · `member_id` int (→ members) · `loaned_on` date · `returned_on` date |
|
||||
|
||||
Relationships: `books.author_id → authors.author_id` (1:n); `loans` joins
|
||||
`books` and `members` (the m:n bridge). Show `shortid` on the Types page via
|
||||
a small standalone example, not by complicating this schema.
|
||||
|
||||
## asciinema casts [DECIDED, details OPEN]
|
||||
|
||||
@@ -81,20 +122,23 @@ Direction (to confirm in the 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.
|
||||
**Resolved (2026-06-05):**
|
||||
1. ~~Depth / organising spine~~ → **Pragmatic** four-section split (see
|
||||
Structure above).
|
||||
2. ~~Page granularity~~ → **one page per topic / command-family**, both
|
||||
modes per page (see Structure).
|
||||
3. ~~Standard example dataset~~ → **the library** (schema above).
|
||||
4. ~~Simple-vs-advanced pairing~~ → **show both where both apply** (see
|
||||
Examples).
|
||||
5. ~~"Planned" callout~~ → standard `:::caution[Planned]` aside (see above).
|
||||
6. ~~Reference generation vs hand-writing~~ → **hand-write now** (command
|
||||
surface is settled bar H1a output; small later adjustments expected).
|
||||
|
||||
**Still open:**
|
||||
7. **Versioning.** Version selectors at/after v1, or single-version for
|
||||
launch? (Leaning single-version for launch.)
|
||||
8. **SEO/meta conventions.** Title/description patterns, Open Graph — settle
|
||||
with Phase B (landing) and the `site` URL.
|
||||
9. **Cast scripting toolchain.** Confirm the scripted-input driver
|
||||
(`asciinema-automation`/autocast vs alternative) via a test run; define
|
||||
the `.cast` script format + storage location. (Execution task, in flight.)
|
||||
|
||||
Reference in New Issue
Block a user