docs(nav): one recipe catalogue, and the unreachable pages are reachable - #498
Conversation
The cookbook page and the recipe folder's index each carried a hand-maintained table of all twenty-two recipe pages. They agreed on which pages exist and disagreed on ten descriptions in each direction — the folder index named PDF417 and DataMatrix among the barcode symbologies while the cookbook did not; the cookbook was fuller on themes, transforms and page backgrounds. Neither was a subset, so neither could simply replace the other. Merged into the page the README and the documentation index both point at, taking the better description of each pair. The folder file keeps the one job GitHub gives it, being what you see when you open the directory, and says where the catalogue is rather than holding a copy that drifts. The documentation index stops describing the two as an index and a coverage map; they were the same list. The archive index named its files in code spans rather than links, so the folder's own table of contents led nowhere, and implementation-guide.md was not listed at all. All three are linked now, with what replaced the third. The two notes beside the committed benchmark baseline — the pre-optimization capture and the before/after it was ratcheted against — had no inbound link from anywhere in the repository. The benchmark guide names them where it explains the baseline they produced. The starting-point table asked three "yes" questions — a known template family, pixel-level control, a re-usable new document type — so a reader generating an ordinary report from data matched none of them and fell off the end of the table. The DSL is the default answer, not a fallback. ./mvnw -B -ntp clean verify — BUILD SUCCESS, 692 tests in the closing module.
9993377 to
3a37c95
Compare
|
You are right, and I verified it rather than taking the account on trust — git says exactly what you said:
So the April notes predate the baseline by six weeks and produced nothing that feeds it. I read the two files' titles and inferred a lineage instead of checking. That is the failure mode this whole series of PRs has been fixing in other people's prose, which makes it a poor one to commit. Corrected. The paragraph now says the notes are historical context only, dates the April capture, and states plainly that neither produced the baseline nor tracks it — the JSON was cut separately when the verdict gate landed and has been re-measured independently since. It also now tells the reader to read the JSON's own I also moved the aside out of the middle of the refresh procedure: my first attempt dropped it between "this is the baseline" and "refresh it only for a verified improvement", splitting one instruction in half. It now sits with the provenance sentence at the end of that section. The CHANGELOG carried the same invented link — "the before/after it was ratcheted against" — and is fixed too. The PR body above is stale on this point; treat this comment as the correction. On the non-blocking note: a guard asserting every
|
1 participant
Why
Four navigation defects, all of the same shape: a reader cannot get to something, or gets to two versions of it.
Two recipe catalogues. docs/recipes.md and docs/recipes/README.md each carried a hand-maintained table of all 22 recipe pages. They agreed on which pages exist — and disagreed on the descriptions, in both directions: the folder index was materially richer on 10 rows (it names PDF417 and DataMatrix among the barcode symbologies; the cookbook does not), the cookbook on 8 (themes, transforms, page backgrounds, shape-as-container…). Neither was a subset, so "delete one" would have silently dropped content. The documentation index papered over it by calling one an index and the other a coverage map; they were the same list.
Unreachable pages. The archive index named its files in code spans, not links — a table of contents that leads nowhere — and
implementation-guide.mdwas not listed at all, which is why an orphan sweep flags it. The two notes beside the committed benchmark baseline,BASELINE_SUMMARY.mdandCOMPARISON.md, had no inbound link from anywhere in the repository.A decision table with no default. docs/getting-started.md asked three "yes" questions — known template family, pixel-level control, re-usable new document type. A reader generating an ordinary report from data matches none and falls off the end.
What changed
docs/recipes.md, taking the better description of each pair, so nothing is lost. Verified by diffing the two tables key-by-key before and after; 11 rows took the folder's wording, the other 11 kept the cookbook's.docs/recipes/README.mdkeeps the one job GitHub gives it — being what renders when you open the directory — and points at the catalogue instead of holding a second copy.docs/README.mdstops describing the pair as two different things.implementation-guide.mdwith what replaced it (the extension guide and the package map).docs/operations/benchmarks.mdnames the two baseline notes where it explains the baseline they produced.One planned item turned out to be already done
The plan's first Phase 6 action was "move
## Scope and comparisonbelow## Architecture". It already is —## Architectureat README.md:298,## Scope and comparisonat :331. That instruction was carried over from an earlier plan written when the order was the other way round, and the reorder landed before this line was ever executed. Recorded rather than acted on; no README change here.Verification
./mvnw -B -ntp clean verify—BUILD SUCCESS, exit 0, 692 tests in the closing module.CanonicalSurfaceGuardTest11 (every relative link resolves),DocumentationCoverageTest5,DocumentationSnippetCompileTest6.Orphan sweep over
docs/before and after:baselines/BASELINE_SUMMARY.mdandbaselines/COMPARISON.mdgo from unreferenced to linked. The four files still reported are the three folderREADME.mds — reached by opening the directory, which a link scanner cannot see — and the archived pages, now linked from their own index.Lane: docs. No production code, no public API.