[Docs] Cut the README to a ten-second pitch and move the rest into docs/ #590

New issue

Closed

opened 2026-07-22 16:18:10 +00:00 by brenno · 1 comment

brenno commented

2026-07-22 16:18:10 +00:00

Owner

Found in the pre-publication first-impression review.

Measurement: wc -w README.md → 3,488 words (~23 KB). The Features list is 24 bullets; measured per line, bullet lengths reach 1,298 characters (README.md:26, OciWacht), 1,160 (:42), 1,123 (:28, MIAUW), 1,109 (:27), 792, 730, 679. Before the first feature the reader has already passed a four-line status header, a name-etymology aside (:11), and a two-paragraph network-transparency blockquote (:13-15) whose second paragraph is 1,900 characters.

Why this matters now: a visitor cannot answer "what is this and is it for me" in ten seconds, because the answer is interleaved with caveats written for a reader who has been here before. The material is good; the placement is wrong.

Proposal: reduce Features to one line each (~15 words), moving the long text to docs/USER_GUIDE.md where most of it already exists. Compress the network blockquote to two sentences plus the link to docs/PRIVACY.md. Target: under 800 words above the Documentation table.

See also the separate issues on screenshots, on the alpha banner, and on moving the correction notes out of the README — together those four decide what the front page looks like on day one.

Found in the pre-publication first-impression review. **Measurement:** `wc -w README.md` → 3,488 words (~23 KB). The Features list is 24 bullets; measured per line, bullet lengths reach 1,298 characters (`README.md:26`, OciWacht), 1,160 (`:42`), 1,123 (`:28`, MIAUW), 1,109 (`:27`), 792, 730, 679. Before the first feature the reader has already passed a four-line status header, a name-etymology aside (`:11`), and a two-paragraph network-transparency blockquote (`:13-15`) whose second paragraph is 1,900 characters. **Why this matters now:** a visitor cannot answer "what is this and is it for me" in ten seconds, because the answer is interleaved with caveats written for a reader who has been here before. The material is good; the placement is wrong. **Proposal:** reduce Features to one line each (~15 words), moving the long text to `docs/USER_GUIDE.md` where most of it already exists. Compress the network blockquote to two sentences plus the link to `docs/PRIVACY.md`. Target: under 800 words above the Documentation table. See also the separate issues on screenshots, on the alpha banner, and on moving the correction notes out of the README — together those four decide what the front page looks like on day one.

brenno added the

docs

label

2026-07-22 16:18:10 +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