[Docs] Move the dated correction notes out of the README first screen #621

New issue

Closed

opened 2026-07-22 16:21:51 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:21:51 +00:00

Owner

Found in the pre-publication documentation review.

Evidence: there are 16 (Corrected YYYY-MM-DD…) notes across the public .md files, and 25 dated meta-notes in total counting (Noted …) and (Added …). Two of them sit at the most-read positions in the project: README.md:15 — the highlighted blockquote about network traffic, directly under the introduction, carrying two stacked corrections in a single parenthesis (2026-07-21 and 2026-07-22) — and README.md:42, the last feature bullet.

docs/README.md:107-129 codifies the practice explicitly: "Corrections carry a date, in the text… leave the old ones standing."

Why this matters now: the rule itself is defensible and unusually honest, and inside docs/ it works — a reader there is already engaged. In the README it works against itself. The first substantive paragraph an outsider reads ends by explaining that the previous version of that paragraph was wrong, and the second correction is dated today. To someone who knows nothing about the project that reads as instability, when it is meant to read as reliability.

Proposal: keep the rule in docs/, take it out of the README. Add one ## Errata section at the foot of the README with the two notes (date, what it said, what it says now) and leave the running text clean. No information is lost, and two paragraphs read as statements again. Record the exception in docs/README.md under How these documents are maintained.

Found in the pre-publication documentation review. **Evidence:** there are **16** `(Corrected YYYY-MM-DD…)` notes across the public `.md` files, and 25 dated meta-notes in total counting `(Noted …)` and `(Added …)`. Two of them sit at the most-read positions in the project: `README.md:15` — the highlighted blockquote about network traffic, directly under the introduction, carrying **two stacked corrections in a single parenthesis** (2026-07-21 and 2026-07-22) — and `README.md:42`, the last feature bullet. `docs/README.md:107-129` codifies the practice explicitly: "Corrections carry a date, in the text… leave the old ones standing." **Why this matters now:** the rule itself is defensible and unusually honest, and inside `docs/` it works — a reader there is already engaged. In the README it works against itself. The first substantive paragraph an outsider reads ends by explaining that the previous version of that paragraph was wrong, and the second correction is dated today. To someone who knows nothing about the project that reads as instability, when it is meant to read as reliability. **Proposal:** keep the rule in `docs/`, take it out of the README. Add one `## Errata` section at the foot of the README with the two notes (date, what it said, what it says now) and leave the running text clean. No information is lost, and two paragraphs read as statements again. Record the exception in `docs/README.md` under *How these documents are maintained*.

brenno added the

docs

label

2026-07-22 16:21:51 +00:00

brenno referenced this issue from a commit

2026-07-22 17:07:09 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue from a commit

2026-07-22 17:12:52 +00:00

docs(readme): een voorpagina die in tien seconden te lezen is (#582 #590 #591 #611 #619 #620 #621 #635)

brenno referenced this issue

2026-07-22 17:14:10 +00:00