The documentation system works, and nine changes to it were accepted
77 of 79 concepts fit without a fight; the nine changes fix the rest, and the second round applies them.
The system carried a hard product, and writing true examples found real bugs
The documentation system works. The contexts, the three folders, the meta block, precise words and generated maps carried a very complicated product well.
Five things fit especially well:
- Contexts fell out of the code. Each of the six maps to a repository or a crate. No concept was homeless.
- The three folders fit 77 of 79 docs without thought Measured.
- Precise words found the real confusion. Six words mean two or three things in the code. Silicon's worst errors sit exactly on them.
- "Summary first, then a worked example" is the test that matters. An example has to be true, so writing it forced a full read of the code path. That is how the update history loss, the lost deterministic state and the vote shift were found.
- Maps are cheap. One small script made all 15 maps and word pages and checked every link, in under a second Measured.
The 300-line limit per doc was never close. The longest full doc is about 110 lines.
Nine places did not fit, and all nine fixes were accepted
Each change below comes from a real case in this test. All nine were accepted, and the second round of docs applies them. None touches the three folders or the meta block:
- Rename the area to docs/contexts/<context>/Today a path says domain twice: docs/domain/<context>/domain/. A search for /domain/ matched every context doc. Keep the three folder names.
- Add an issues: field for behaviour that is a bug todayUpdate losing its own history had no honest place. The doc says what happens now and links the issue; the reviewer checks both.
- Add a doc type formatThe state file, cyan.yaml and the resolver request body are file formats, not things or flows. They belong in domain/ as format.
- Add a doc type guardSession release, created folder cleanup and readiness checks say what must hold when something fails. Put them in implementation/.
- Write code paths as <repo>/<path>Every full doc names two or three repositories. Each repository checks only its own paths; the reviewer checks the rest.
- Add a guides/ areaSilicon's 52 how-to and tutorial pages had no home. Guides use the contexts' words but never define them.
- Rename the rarer concept, keep the short wordDocs written to avoid a bare "resolver" still used it 51 times. Keep "resolver" for conflict resolvers; rename the code's dependency resolver.
- Add stub: true71 stubs have no status field, and "not written yet" trips the history check. Maps show stubs; the history check skips them.
- Allow "Inferred:" in Why this wayEvery full doc has reasons with no decision record behind them. Allow them, marked, until a record exists; the reviewer flags each one.
The first change is the one you will notice most, so it is also asked on its own. Decide thisQ2Do we rename docs/domain/<context>/ to docs/contexts/<context>/?
Two cases sat awkwardly between the domain and architecture folders
The three-folder split felt forced twice. Neither breaks the system, but both are worth knowing.
Commands are both a thing and a flow. create and update are features, so they belong in domain/. But most of what they do is a flow. The trial tree put the flow in architecture/batch-run.md and kept short domain docs. Two docs for one command is one too many for a reader.
An API is looked for in the wrong place. The coordinator's routes are a surface, so they live in architecture/. Readers look for them under domain/. Generated maps fix this, but without maps it is awkward.
Smaller notes from the test:
- A word list needs to point at a word in another context.
- The generated map is a list, not a flow; a hand-written "create, end to end" doc filled that gap.
- Line numbers rot, so
code:should name paths and the prose should name symbols. - The history check should also read code comments: silicon had no history text, but the code had 28 history comments.