[Docs] No document over 600 lines has a table of contents #623

New issue

Closed

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

brenno commented

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

Owner

Found in the pre-publication documentation review.

Evidence: seven documents exceed 600 lines — USER_GUIDE.md (2,992), OCIWACHT.md (2,668), FILE_FORMAT.md (2,253), CHECKS.md (809), SECURITY_DESIGN.md (681), SOURCE_MAP.md (635), ARCHITECTURE.md (618) — together 10,656 lines, with zero tables of contents.

In USER_GUIDE.md: 25 H2 and 62 H3 headings, only five internal anchor links across nearly 3,000 lines, and no images (the one ![ at line 517 is a Markdown example). Its largest section, Slide types, is 681 lines on its own — as long as the whole of SECURITY_DESIGN.md.

Mitigating: the in-app reader (lib/widgets/reader/documentation_search_tab.dart) has full search across every bundled document, so inside the app this is tolerable. On the repository page it is not — there USER_GUIDE.md is 2,992 lines of scrolling with no way in, and it is exactly the file the README points at for "using the app".

Proposal: add a ## Contents block with the H2 anchors directly under the masthead of USER_GUIDE.md and FILE_FORMAT.md — the two an outsider actually opens. About 30 lines each, no text changes. Screenshots in the user guide are a bigger job; track that separately, not for 0.1.0.

Found in the pre-publication documentation review. **Evidence:** seven documents exceed 600 lines — `USER_GUIDE.md` (2,992), `OCIWACHT.md` (2,668), `FILE_FORMAT.md` (2,253), `CHECKS.md` (809), `SECURITY_DESIGN.md` (681), `SOURCE_MAP.md` (635), `ARCHITECTURE.md` (618) — together 10,656 lines, with **zero** tables of contents. In `USER_GUIDE.md`: 25 H2 and 62 H3 headings, only **five** internal anchor links across nearly 3,000 lines, and no images (the one `![` at line 517 is a Markdown example). Its largest section, *Slide types*, is 681 lines on its own — as long as the whole of `SECURITY_DESIGN.md`. **Mitigating:** the in-app reader (`lib/widgets/reader/documentation_search_tab.dart`) has full search across every bundled document, so inside the app this is tolerable. On the repository page it is not — there `USER_GUIDE.md` is 2,992 lines of scrolling with no way in, and it is exactly the file the README points at for "using the app". **Proposal:** add a `## Contents` block with the H2 anchors directly under the masthead of `USER_GUIDE.md` and `FILE_FORMAT.md` — the two an outsider actually opens. About 30 lines each, no text changes. Screenshots in the user guide are a bigger job; track that separately, not for 0.1.0.

brenno added the

docs

label

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

brenno referenced this issue from a commit

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

docs: claims en cijfers die niet meer klopten (#602 #599 #614 #640 #634 #587 #623)

brenno referenced this issue from a commit

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

docs: claims en cijfers die niet meer klopten (#602 #599 #614 #640 #634 #587 #623)

brenno referenced this issue

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