From 8927a855b396ef6c6d1a20fb7782c2c18d58fc23 Mon Sep 17 00:00:00 2001 From: Marty Nelson Date: Sun, 21 Jun 2026 12:32:36 -0700 Subject: [PATCH] docs: doc-review & refresh plan (catalog + two-track structure) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catalog: 29 docs (18 current, 5 stale, 6 ref/meta). Two audience tracks (human story: subtraction spine → state-to-layout; LLM: navigation + the 5-level teaching arc). Gaps: no L5 (KeyedList/frames) doc, no standalone subtraction-spine doc. Currency: kill channel()/blocks/Controller refs. Prune: docs/ essay-dupes superseded by docs/topics/. Target structure + tackle order. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01156Jwbhv8ue51zDZdvdmbM --- docs/design/doc-review.md | 84 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/design/doc-review.md diff --git a/docs/design/doc-review.md b/docs/design/doc-review.md new file mode 100644 index 0000000..75776c6 --- /dev/null +++ b/docs/design/doc-review.md @@ -0,0 +1,84 @@ +# Documentation review & refresh — plan + +Catalog pass (2026-06): **29 docs — 18 current, 5 stale, 6 reference/meta.** +The teaching arc's first four levels are solid; the gaps + stale spots map onto +the reorg and the talk's framing. + +## Two audiences, two tracks + +- **Human track — the story.** Move the reader from **state-based** (inward + gaze: code/tech) to **layout-based** (outward gaze: UX + value). Spine: the + *"without ___"* hook (no vDOM / no controlling renderer / no JS creating DOM / + no state) → **subtraction, not replacement** → state→layout. Target reader: + someone who wants to build more compelling / differentiated web experiences. +- **LLM track — navigation + the teaching arc.** Navigate to the corpus the + model already knows (DOM / JS / platform): push from the *subtracted* (vDOM, + React vocab), pull to the *unlocked* (DOM API, full JS). Teaching arc, opt-in + depth, each level independently useful: + 1. JSX as DOM + 2. Props & Attributes + 3. Async composition (promises, observables, async iterators, EventTargets) + Channel + 4. Rerendering (the rerenderer) + 5. **KeyedList + custom elements — the "new frame for layout"** +- **Balance per doc:** the hook is paid off by *how it works* — so foundational + docs lead with **mechanism** (answers the curiosity); practice docs lead with + **how to use**. + +## Gaps (net-new, highest value) + +1. **Level 5 — KeyedList + custom-element frames.** Shipped; no doc. The arc + stops at async composition. → NEW `docs/topics/keyed-list.md` (or + `dynamic-lists-and-frames.md`): when you need a frame (the recognition test), + KeyedList authoring, the controller/source patterns. +2. **The subtraction spine.** The core reframe is scattered (lives partly in + `coming-from-react.md`) with no standalone anchor. → NEW spine doc: the + "without" hook → subtraction → state→layout. The **human-track entry point.** + +## Currency (stale references to kill) + +`channel()` → `` · `blocks`/`KeyedBlock` → KeyedList · `Controller`/ +`Updater` (gone) · `use()` · the old package set / chronos / sandbox / +standalone vite-plugin. +- Hotspots: `docs/topics/maya-runtime.md` (Channel + blocks sections), + `docs/topics/async-and-channels.md`, scattered top-level docs. + +## Prune (essay-form dupes, superseded by `docs/topics/`) + +- `docs/ASYNC-PATTERNS.md`, `docs/async-rendering-patterns.md`, `docs/maya.md`, + `docs/hypermedia.md` — essay versions of topic docs, now carrying old APIs → + archive or merge the still-useful bits (e.g. View/CardView → `workflow.md`). +- `docs/scratchpad/*` — stale exploratory → archive. +- **Keep:** `docs/MENTAL-MODEL.md` (historical origin trace). **Assess:** + `docs/MYTHOS.md` (philosophy — fold into the spine doc, or keep as-is). + +## Target structure (`docs/topics/`) + +``` +Foundations + subtraction / the-platform-bet ★NEW — the human spine + the "without" hook + jsx-as-dom (L1 · current) + attributes-and-properties (L2 · currency check) + composition (the {…} slot · current) + components (function / class = constructor · current) +Async & updates + async-and-channels (L3 · currency: , not channel()) + rerendering (L4 · ensure standalone coverage vs maya-runtime) + hypermedia (events as deltas — layout not state · current) +Dynamic & frames + keyed-list ★NEW — L5 · KeyedList + custom-element frames +Internals maya-runtime (currency) · thoth-compiler +Practice workflow · authoring-style · typescript · build-and-integration +Transitions coming-from-react · known-limitations +For-AI for-llms (navigation; sandbox refs removed) +``` + +## Tackle order (each its own small PR) + +1. **NEW: level-5 KeyedList / frames topic** — completes the arc; documents the + shipped headline feature; freshest context now. +2. **NEW: subtraction-spine doc** — the human-track anchor + the "without" hook. +3. **Currency pass** — `maya-runtime`, `async-and-channels`, scattered refs. +4. **Prune** — the `docs/` essay-dupes + `scratchpad/`. +5. **Package READMEs** — maya stub, thoth's new role, valhalla. +6. **Re-knit navigation** — `docs/index`, `topics/index`, README "Start here" to + the refreshed structure + the two tracks.