docs: bring stale claims in line with what shipped#110
Merged
Conversation
Documentation hadn't caught up with Phases 2-5. Concrete fixes: - serving/README.md opens with 'the answer is: not really' even though the Phase 5 ADR (lower in the same file, and the postmortem itself) shows Go won throughput, latency, and memory. Rewritten to match. - README.md called the BPR speedup '~30x' while the ADR and benchmarks/profile.md both cite '~51x'. Bumped to ~51x to match. - README.md algorithm table called BPR 'numpy SGD' — that was true pre-Phase-2. Now 'Rust+PyO3 kernel; Python fallback'. - docs/index.md said the library had 'five algorithms' (out of date by five: BPR, ALS, ContentBased, TwoTowerCF, HybridRecommender all ship). Rewritten to list all ten, point at api.md, and use the source-install recipe since we're not on PyPI yet. - docs/choosing_an_algorithm.md BPR 'when it isn't' still mentioned 'numpy SGD loop' as the bottleneck — that loop was rewritten in Phase 2. Reframed to ALS as the alternative. The k-NN / SVD 'data source' columns also updated to reflect Phase 3's sparse rewrite. - ROADMAP.md was stuck pre-Phase-2: book recommender listed as in-progress (shipped), #77 sparse work listed as next (shipped), Rust kernel and serving experiment entirely absent. Rewrote Shipped to reflect reality; Next is now release + a couple of follow-ups. - src/recommender_systems/books.py module docstring used the word 'showcase' — the one remaining instance in the tree, which renders into api.md via mkdocstrings. Replaced. - docs/evolution/02-rust-kernel-bpr.md pointed at 'tests/test_fit_speed.py' — the actual path is 'tests/benchmarks/test_fit_speed.py'.
JohnJacob-coder
approved these changes
May 28, 2026
JohnJacob-coder
left a comment
Collaborator
There was a problem hiding this comment.
Checked each correction against main. The ~51x and the Rust-kernel BPR row match the Phase 2 ADR and benchmarks/profile.md; the k-NN/SVD doc rows match the Phase 3 sparse rewrite; the serving README intro no longer contradicts its own ADR; and the books.py docstring was the last 'showcase' anywhere (grep across README/docs/src/serving is clean now). ruff/mypy/pytest green, mkdocs --strict builds with no warnings. Good catch on the doc drift.
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
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.
Documentation hadn't caught up with Phases 2-5. Pulled out of the audit as the highest-value cluster — seven concrete corrections, no code change.
serving/README.mdREADME.md:67benchmarks/profile.mdREADME.md:122docs/index.mdpip install recommender-systemsdocs/choosing_an_algorithm.mdROADMAP.mdsrc/recommender_systems/books.pyapi.mdvia mkdocstringsdocs/evolution/02-rust-kernel-bpr.md:73tests/test_fit_speed.pytests/benchmarks/test_fit_speed.pyVerification
ruff check/ruff format --check/mypycleanpytest— 137 passed, 1 skipped (kernel without build), 7 deselectedmkdocs build --strict— 0 warnings