Cut the README to an introduction, refresh the docs - #7
Merged
Conversation
The README had grown into a second copy of the documentation: a policy table, the API surface, install and usage, when-to-use guidance, and a summary of the evidence, all of which existed again under docs/. Two copies of a fact is one copy that goes stale, and several had. It is now three paragraphs saying what the library is and what problem it solves, followed by the index. What it carried has moved to owners rather than being deleted. Install, the worked example, the AdaptiveCache API and the prior-art list are a new getting-started page; the fit guidance is in design.md next to the mechanism it depends on; the headline findings open evidence.md, which is where the numbers already lived. Fifteen claims across the docs were wrong or stale and are corrected. The architecture diagram named a bandit the root module does not depend on and function names that no longer exist. The per-request walkthrough said a write counts a hit or miss, which only reads do, and said epochs always run on a background goroutine, which request-counted epochs do not. The advisor sample output listed an arm the example never constructs. The capacity gate was described as skipping the epochs of whichever arm is under-filled, when it reads the active policy alone and skips every arm's measurement together. Cap was attributed to Cacher rather than Policy. The fleet page said only integers cross the wire and then listed a policy name, where the wire carries the numeric PolicyType precisely so a rename cannot split a fleet's counters. The fleet evidence was re-measured rather than left marked stale, and it moved: pooling now gains 3.6 points on a starved fleet, and coordinating every 10-25ms is worth a fraction of a point where every setting used to cost something. Two tuning figures were recomputed from the current runs - cold migration costs 30.7 points on OLTP, not 28, and the stability gates cost 20.6 on LIRS loop, not 37. Release notes now say on their face that they are historical records of the release they describe, so their numbers stop reading as current.
sshaplygin
force-pushed
the
docs/refresh
branch
from
August 24, 2026 21:48
a6548b0 to
0c651ff
Compare
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.
The README had become a second copy of the documentation — a policy table, the API surface, install and usage, when-to-use guidance, and a summary of the evidence, all of which existed again under
docs/. Two copies of a fact is one copy that goes stale, and several had. It is now three paragraphs saying what the library is and what problem it solves, followed by the index.Nothing was dropped, only moved to an owner:
AdaptiveCacheAPI and the prior-art list → a newdocs/getting-started.mddocs/design.md, next to the mechanism that guidance depends ondocs/evidence.md, where the numbers already livedCorrections
Fifteen claims were wrong or stale. The notable ones:
AdaptiveCache.Resizewas described as passing its new capacity through to every arm; shadows are resized to the miniature that corresponds to it.Capwas attributed toCacherrather thanPolicy.PolicyType, precisely so that a rename cannot silently split a fleet's counters.Randomis the other, by design.Re-measured
The fleet section was re-run rather than left marked stale, and the result moved: pooling now gains 3.6 points on a starved fleet, and coordinating every 10–25ms is worth a fraction of a point where every setting used to cost something. Two tuning figures were recomputed — cold migration costs 30.7 points on OLTP rather than 28, and the stability gates cost 20.6 on LIRS
looprather than 37.Release notes now state on their face that they are historical records of the release they describe, so their numbers stop reading as current.
Docs only: no Go file is touched, and every internal link and heading anchor resolves.