Skip to content

docs: bring stale claims in line with what shipped#110

Merged
JohnJacob-coder merged 1 commit into
mainfrom
docs/fix-stale-claims
May 28, 2026
Merged

docs: bring stale claims in line with what shipped#110
JohnJacob-coder merged 1 commit into
mainfrom
docs/fix-stale-claims

Conversation

@Burton-David

Copy link
Copy Markdown
Owner

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.

File Problem Fix
serving/README.md Opens with "the answer is: not really" — directly contradicts the Phase 5 ADR (same file, lower down) showing Go won throughput/latency/memory Rewrite intro to match measurement
README.md:67 Claims BPR is "~30×" faster Bump to "~51×" to match the ADR + benchmarks/profile.md
README.md:122 Algorithm table called BPR "numpy SGD" "Rust+PyO3 kernel; Python fallback"
docs/index.md "Five algorithms out of the box" + pip install recommender-systems List all ten algorithms; source-install recipe with the Rust toolchain prereq
docs/choosing_an_algorithm.md BPR "when it isn't" still mentioned the numpy SGD bottleneck (gone since Phase 2); k-NN/SVD rows said "dense" Reframed BPR to ALS-as-alternative; updated data-source columns to reflect Phase 3's sparse rewrite
ROADMAP.md 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 release + ContentBased-on-sparse
src/recommender_systems/books.py Module docstring used "showcase" — the one remaining instance, surfaced into api.md via mkdocstrings "recommender"
docs/evolution/02-rust-kernel-bpr.md:73 Pointed at tests/test_fit_speed.py tests/benchmarks/test_fit_speed.py

Verification

  • ruff check / ruff format --check / mypy clean
  • pytest — 137 passed, 1 skipped (kernel without build), 7 deselected
  • mkdocs build --strict — 0 warnings

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 JohnJacob-coder left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@JohnJacob-coder JohnJacob-coder merged commit a8e7907 into main May 28, 2026
3 checks passed
@JohnJacob-coder JohnJacob-coder deleted the docs/fix-stale-claims branch May 28, 2026 00:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants