Doc system test
Page 5 of 6 · Verdict

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.

What fit

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 changes

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:

  1. 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.
  2. Add an issues: field for behaviour that is a bug today
    Update losing its own history had no honest place. The doc says what happens now and links the issue; the reviewer checks both.
  3. Add a doc type format
    The state file, cyan.yaml and the resolver request body are file formats, not things or flows. They belong in domain/ as format.
  4. Add a doc type guard
    Session release, created folder cleanup and readiness checks say what must hold when something fails. Put them in implementation/.
  5. 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.
  6. Add a guides/ area
    Silicon's 52 how-to and tutorial pages had no home. Guides use the contexts' words but never define them.
  7. Rename the rarer concept, keep the short word
    Docs written to avoid a bare "resolver" still used it 51 times. Keep "resolver" for conflict resolvers; rename the code's dependency resolver.
  8. Add stub: true
    71 stubs have no status field, and "not written yet" trips the history check. Maps show stubs; the history check skips them.
  9. Allow "Inferred:" in Why this way
    Every 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>/?

Where it felt forced

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.