Before the three-repo carve triplicates them, cut the documentation to the point.
Problem
The prose docs run ~11.6k lines and are discussionary: rationale essays, planning-material references, repeated context, and aspirational targets stated as design fiction (docs/08-platform-generalisation is 1015 lines). ADRs carry verbose Context sections and cross-references. Several docs have drifted from the code: ADR-0013 is still status: proposed and uses the chassis vocabulary the code renamed to keeper. Dated point-in-time reports (backtest/load/e2e/baselines) would be triplicated at the cut.
Scope
- Prose/design docs (docs/00-08, docs/design, deployment, README, tutorial, sdk.md, production.md, qa-signoff).
- ADRs (docs/adr): trim cruft, keep each decision, mark superseded or obsolete ones as superseded.
- Operations: delete dated point-in-time reports; trim runbooks to the procedure.
- Rustdoc
//! crate and module headers: cut discursive or planning prose and stale vocabulary; comments only, never code or wit.
Standard
Extremely terse and factual. No discussionary or rationale-essay prose, no planning-material references, no needless repetition across docs. Oxford British -ize, no em dashes. Fix routine drift silently; flag substantive deviations (a doc describing behaviour the code does not have) separately.
Done when
Delivered as per-area PRs into dev/m1 before the carve (#407), each terse to standard, with a consolidated list of the substantive deviations found.
Problem
The prose docs run ~11.6k lines and are discussionary: rationale essays, planning-material references, repeated context, and aspirational targets stated as design fiction (docs/08-platform-generalisation is 1015 lines). ADRs carry verbose Context sections and cross-references. Several docs have drifted from the code: ADR-0013 is still
status: proposedand uses thechassisvocabulary the code renamed tokeeper. Dated point-in-time reports (backtest/load/e2e/baselines) would be triplicated at the cut.Scope
//!crate and module headers: cut discursive or planning prose and stale vocabulary; comments only, never code or wit.Standard
Extremely terse and factual. No discussionary or rationale-essay prose, no planning-material references, no needless repetition across docs. Oxford British -ize, no em dashes. Fix routine drift silently; flag substantive deviations (a doc describing behaviour the code does not have) separately.
Done when
Delivered as per-area PRs into dev/m1 before the carve (#407), each terse to standard, with a consolidated list of the substantive deviations found.