[Feature] Guard that documentation is right, not only that it is registered #539

New issue

Closed

opened 2026-07-22 11:21:23 +00:00 by brenno · 0 comments

brenno commented

2026-07-22 11:21:23 +00:00

Owner

Problem / motivation

docs_registration_test guards that every document under docs/ is reachable: bundled as an asset, given a reader tile, with a translated title. That is a real guard, and it is a guard about plumbing.

It says nothing about whether the document is true, current, or followable. The precedent is on the record: the d7b609bf guides were generated fiction — well-formed, correctly registered, describing behaviour that did not exist — and they were removed on 2026-07-19. Registration would not have caught that, and did not.

Smaller instances keep turning up. In this session alone: docs/CHECKS.md said serviceUiImportBaseline was 8 while the code said 4, and the PR template listed 8 supported languages against an actual 32. Both were plumbing-correct and factually wrong.

From the CRA position decision (#519): the third direction named there was "sufficient and clear documentation" — meaning right, not merely present.

Proposed solution

Two separable pieces.

Mechanical, cheap: extend the class of check that already caught the two examples above — a claim in prose that restates a constant in code should be derived or compared, not retyped. test/docs_enum_counts_test.dart and the new test/pr_template_consistency_test.dart are the working precedents. Candidates: the ratchet values in CHECKS.md, the language count, the enum counts in API_DOCUMENTATION.md, the file lists in SOURCE_MAP.md.

Human, and the harder half: a periodic pass asking whether a reader who was not there can follow the document — which is what "clear" means and no test can answer. docs/SOURCE_MAP.md is the standing example: it claims a line per lib/ file and was missing 156 of them (#518).

Marp / file-format impact

None.

Alternatives considered

A general "docs must be reviewed every N months" rule — rejected: an unenforceable rule about documentation is itself stale documentation.

**Problem / motivation** `docs_registration_test` guards that every document under `docs/` is reachable: bundled as an asset, given a reader tile, with a translated title. That is a real guard, and it is a guard about *plumbing*. It says nothing about whether the document is true, current, or followable. The precedent is on the record: the d7b609bf guides were generated fiction — well-formed, correctly registered, describing behaviour that did not exist — and they were removed on 2026-07-19. Registration would not have caught that, and did not. Smaller instances keep turning up. In this session alone: `docs/CHECKS.md` said `serviceUiImportBaseline` was 8 while the code said 4, and the PR template listed 8 supported languages against an actual 32. Both were plumbing-correct and factually wrong. From the CRA position decision (#519): the third direction named there was "sufficient and clear documentation" — meaning right, not merely present. **Proposed solution** Two separable pieces. *Mechanical, cheap:* extend the class of check that already caught the two examples above — a claim in prose that restates a constant in code should be derived or compared, not retyped. `test/docs_enum_counts_test.dart` and the new `test/pr_template_consistency_test.dart` are the working precedents. Candidates: the ratchet values in `CHECKS.md`, the language count, the enum counts in `API_DOCUMENTATION.md`, the file lists in `SOURCE_MAP.md`. *Human, and the harder half:* a periodic pass asking whether a reader who was not there can follow the document — which is what "clear" means and no test can answer. `docs/SOURCE_MAP.md` is the standing example: it claims a line per `lib/` file and was missing 156 of them (#518). **Marp / file-format impact** None. **Alternatives considered** A general "docs must be reviewed every N months" rule — rejected: an unenforceable rule about documentation is itself stale documentation.

brenno added the

accepted

enhancement

labels

2026-07-22 11:21:23 +00:00

brenno referenced this issue from a pull request that will close it,

2026-07-22 13:53:11 +00:00

feat: meet doorlooptijd, ratchetbeweging en of de documentatie klopt #558

brenno referenced this issue from a commit

2026-07-22 13:53:13 +00:00

docs(checks): ververs de uitslag, en haal het verdwenen budget eruit

brenno closed this issue