book: retire the human pages of docs/ #599

New issue

Open

opened 2026-10-29 14:25:46 +00:00 by orion · 0 comments

orion commented

2026-10-29 14:25:46 +00:00

Collaborator

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged.

Scope

Finish the split once the sections above have landed: delete docs/glossary.md, the German docs/translations/de/guide/* and docs/translations/de/site/*, and every page of docs/ whose content now lives in the book and that no skill reads. Point docs/index.md at the book. Redo the audit numbers of #582 for the book and post them on the epic.

Acceptance criteria

Every page has the kind page and is written as book/CONCEPT.md, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections
Every trb run and trb error block has its output block with the real output; torb docs check book, torb docs index --check book and torb docs site book --check pass in CI
The signature features of book/CONCEPT.md that the area touches are shown, not just named
The old pages of docs/ this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which)
docs skill docs skills --check stays green: a page a skill is built from is either kept or the skill is moved to read the book
No page of docs/ is linked from the book, and no page of the book links into docs/design, docs/contributing or docs/internals
The audit on #582 is repeated for book/: pages, words, runnable examples with output, list lines

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged. ## Scope Finish the split once the sections above have landed: delete `docs/glossary.md`, the German `docs/translations/de/guide/*` and `docs/translations/de/site/*`, and every page of `docs/` whose content now lives in the book and that no skill reads. Point `docs/index.md` at the book. Redo the audit numbers of #582 for the book and post them on the epic. ## Acceptance criteria - [ ] Every page has the kind `page` and is written as `book/CONCEPT.md`, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections - [ ] Every `trb run` and `trb error` block has its `output` block with the real output; `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass in CI - [ ] The signature features of `book/CONCEPT.md` that the area touches are shown, not just named - [ ] The old pages of `docs/` this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which) - [ ] `docs skill docs skills --check` stays green: a page a skill is built from is either kept or the skill is moved to read the book - [ ] No page of `docs/` is linked from the book, and no page of the book links into `docs/design`, `docs/contributing` or `docs/internals` - [ ] The audit on #582 is repeated for `book/`: pages, words, runnable examples with output, list lines

orion added the

loop

label

2026-10-29 14:25:46 +00:00

orion added a new dependency

2026-10-29 14:25:51 +00:00

#585 docs(book): a book for people, and the site built from it

orion added a new dependency

2026-10-29 14:25:51 +00:00

#587 book: Guide chapters (first project, modelling data, collections, files and formats, testing, native programs, design choices)

orion added a new dependency

2026-10-29 14:25:51 +00:00