Restructure the documentation around Diátaxis - #1
Merged
Merged
Conversation
The nav labels had stopped describing the contents. Both pages under `tutorials/` were explanation essays, there was no tutorial anywhere, and the genuine task recipes were buried inside a troubleshooting page and a threshold page. Diátaxis names that failure directly: a document that mixes learning, tasks, information and understanding serves none of them. Mode mass before: explanation ~55%, reference ~20%, how-to ~15%, tutorial 0%. Four sections now, as tabs. `tutorial/first-measurement.md` is the piece that did not exist — a hand-held lesson using the bundled datasets, so it needs no download, no lemmatiser and no network, and cannot fail. Ten how-to guides, mostly recipes that already existed as subsections of something else. Reference gains a package-level page (`__init__`'s docstring had never rendered anywhere), the LIX band cut-points, the calibration data, and a glossary. Four explanation pages carry the arguments that were miscategorised as tutorials. `quickstart.md` and `troubleshooting.md` are gone: each was three modes wearing one title. `docs/examples/` is gone too — Diátaxis has no Examples mode, and those pages were a script, its pasted stdout, and a snippet include. The scripts stay in `examples/`. The docs are now under test. `--doctest-glob=*.md` with `docs` on testpaths runs every `>>>` in every page on every push, which is 12 more test files and the only thing that makes a tutorial's promise of guaranteed success mean anything. Both surviving pages failed that gate when it was switched on. Illustrative code that cannot run — spaCy, a corpus, a network — stays in plain `python` blocks, which are not collected. Two fixes that fell out of the audit rather than the framework. The headline statistic was stale in three files. Ground truth in the committed calibration JSON is 44.52% over 554,861,558 tokens; `docs/index.md`, `readability.py` and `examples/lix_quickstart.py` still carried 38.9% over 493M from the superseded top100k smoke run. The `readability.py` one is a module docstring, so the wrong number was live on Read the Docs, on the claim the package is built around. And the `Contract:` blocks rendered as one paragraph with the bullets as literal text. Griffe does recognise the section — it emits a proper `<details>` — but the body needed the subsection bodies at the same indent as their headers, with a blank line after each. Too deep renders a code block; too shallow merges into a paragraph. Confirmed by grepping the built HTML rather than by eye. The reference pages now show real lists, and `tests/test_docstring_refs.py` caught the line drift the reindent caused, which is what it is for. The README is a front door now: pitch, the two reasons, install, a short quickstart, the data contract, and four links. The four guards, the MATTR warning, the three ways to supply B and the length-policy tour were all second copies of pages that say it better. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The nav labels had stopped describing the contents: both pages under
tutorials/were explanation essays, there was no tutorial anywhere, and the task recipes were buried inside a troubleshooting page and a threshold page.Mode mass before: explanation ~55%, reference ~20%, how-to ~15%, tutorial 0%.
After
quickstart.mdandtroubleshooting.mdare gone — each was three modes wearing one title.docs/examples/too; Diátaxis has no Examples mode. The scripts stay inexamples/.The docs are now under test
--doctest-glob=*.mdwithdocson testpaths. 273 tests, up from 261. Every>>>in every page runs on every push — the only thing that makes a tutorial's promise of guaranteed success mean anything. It caught wrong values in the tutorial and four how-to guides while they were being written.Two fixes from the audit
A stale headline number. Ground truth is 44.52% over 554,861,558 tokens.
docs/index.md,src/saphes/readability.pyandexamples/lix_quickstart.pycarried 38.9% over 493M from the superseded top100k smoke run. Thereadability.pyone is a module docstring, so the wrong number was live on Read the Docs, on the claim the package is built around.Contract:blocks rendered as a paragraph blob. Griffe does recognise the section and emits a proper<details>; the problem was indentation. Bodies now sit level with their subsection headers, so the reference pages show real lists. Confirmed by grepping the built HTML.Also
README slimmed to a front door — the four guards, the MATTR warning, the three ways to supply B and the length-policy tour were second copies of pages that say it better.