Skip to content

Cut the README to an introduction, refresh the docs - #7

Merged
sshaplygin merged 1 commit into
mainfrom
docs/refresh
Aug 24, 2026
Merged

Cut the README to an introduction, refresh the docs#7
sshaplygin merged 1 commit into
mainfrom
docs/refresh

Conversation

@sshaplygin

@sshaplygin sshaplygin commented Aug 24, 2026

Copy link
Copy Markdown
Owner

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:

  • install, the worked example, the AdaptiveCache API and the prior-art list → a new docs/getting-started.md
  • when to use it and when not to → docs/design.md, next to the mechanism that guidance depends on
  • the headline findings → the top of docs/evidence.md, where the numbers already lived

Corrections

Fifteen claims were wrong or stale. The notable ones:

  • 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 (only reads do), and that epochs always run on a background goroutine (request-counted epochs run on the caller's).
  • The advisor-mode sample output listed an arm the example never constructs.
  • AdaptiveCache.Resize was described as passing its new capacity through to every arm; shadows are resized to the miniature that corresponds to it.
  • The capacity gate was described as skipping the epochs of whichever arm is under-filled; 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, then listed a policy name — the wire carries the numeric PolicyType, precisely so that a rename cannot silently split a fleet's counters.
  • W-TinyLFU was called the only non-deterministic arm; Random is 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 loop rather 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.

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
sshaplygin merged commit 69c66fd into main Aug 24, 2026
29 checks passed
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.

1 participant