[Docs] The README links 14 of 31 documents and never links the docs index #619

New issue

Closed

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

brenno commented

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

Owner

Found in the pre-publication documentation review.

Evidence: grep -c "docs/README" README.md → 0. The README table (README.md:124-139) names 14 documents; docs/ holds 31. Unreachable from the README: docs/README.md (the index itself), FAQ.md, TROUBLESHOOTING_GUIDE.md, GLOSSARY.md, SECURITY_DESIGN.md, API_DOCUMENTATION.md, CONTRIBUTING_GUIDELINES.md, DEVELOPMENT_SETUP_GUIDE.md, MIGRATION_GUIDE.md, PERFORMANCE_GUIDE.md, plus three design documents. (PRIVACY.md and ACCESSIBILITY.md appear in running text at :15 and :39, but not in the table.)

Meanwhile docs/README.md has an excellent "New here?" section with five reader paths — user, developer, host, auditor, assistive tech — that nobody finds.

Why this matters now: the README is the only page everyone reads. The three documents a new user needs first (FAQ, Troubleshooting, Glossary) are missing from it, while docs/SOURCE_MAP.md — a 635-line index of lib/ — is present.

Proposal: one line above the table: "Full documentation index: docs/README.md — the five reader paths start there." Plus four rows for FAQ, Troubleshooting, Privacy and Accessibility. Five lines total.

Found in the pre-publication documentation review. **Evidence:** `grep -c "docs/README" README.md` → **0**. The README table (`README.md:124-139`) names 14 documents; `docs/` holds 31. Unreachable from the README: `docs/README.md` (the index itself), `FAQ.md`, `TROUBLESHOOTING_GUIDE.md`, `GLOSSARY.md`, `SECURITY_DESIGN.md`, `API_DOCUMENTATION.md`, `CONTRIBUTING_GUIDELINES.md`, `DEVELOPMENT_SETUP_GUIDE.md`, `MIGRATION_GUIDE.md`, `PERFORMANCE_GUIDE.md`, plus three design documents. (`PRIVACY.md` and `ACCESSIBILITY.md` appear in running text at `:15` and `:39`, but not in the table.) Meanwhile `docs/README.md` has an excellent "New here?" section with five reader paths — user, developer, host, auditor, assistive tech — that nobody finds. **Why this matters now:** the README is the only page everyone reads. The three documents a new user needs first (FAQ, Troubleshooting, Glossary) are missing from it, while `docs/SOURCE_MAP.md` — a 635-line index of `lib/` — is present. **Proposal:** one line above the table: "**Full documentation index: docs/README.md** — the five reader paths start there." Plus four rows for FAQ, Troubleshooting, Privacy and Accessibility. Five lines total.

brenno added the

docs

label

2026-07-22 16:21:50 +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