Skip to content

Cut the README down to what a reader needs - #115

Merged
tonytonycoder11 merged 1 commit into
mainfrom
docs/readme-for-the-reader
Aug 6, 2026
Merged

Cut the README down to what a reader needs#115
tonytonycoder11 merged 1 commit into
mainfrom
docs/readme-for-the-reader

Conversation

@tonytonycoder11

Copy link
Copy Markdown
Contributor

The README was 702 lines and about two hundred of them were not about using this library. It is 555 now
and nothing a reader needs was cut.

The Roadmap section

Three paragraphs of version history, one per release, growing by one every time something ships. That
is CHANGELOG.md restated in prose, which is the failure mode the one-home rule exists to prevent: two
descriptions of the same release, only one of which anybody updates.

The section is now four sentences. The plan is on the board, what shipped is in the changelog, what a
version may change is in STABILITY.md, and each of the three is linked.

Three places that told a story instead of a fact

The footprint table was followed by four paragraphs on the discovery that the GraalVM claim had never
been tested and what building the image turned up. The architecture tree by four on what adding the
second engine proved about the seam. The platforms section argued the Kotlin/JS exclusion, and then
## Architecture argued it again from a different premise, so the two no longer agreed with each other.

What survives of each is the fact and the link that makes it checkable. The GraalVM row keeps its link
to the CI job that produces the 37 ms, because a number nobody can check is worse than no number.

Smaller cuts

The status blockquote was a nine-line feature inventory, and nobody reads an inventory to decide whether
to depend on something; it names what the client covers and points at the board. Scrolling, deleting,
counting and retrieving were four headings for four one-line calls and are one. Tracing and metrics
were one section and a missing one, and are now Observability.

Two links repointed

benchmarks/README.md and docs/migrating-from-qdrant-client.md both linked
#footprint-vs-the-official-client, which is now #compared-with-the-official-client. Fixed here
rather than left to 404.

audit-library.sh reports the repository at standard, with the section order, the status blockquote and
the shipped-state vocabulary all intact.

Two hundred lines of it were not about using this library.

The Roadmap section was the worst of it: three paragraphs of version history
that CHANGELOG.md already owns, restated in prose that drifts from it. The
plan lives on the board and the board is linked, which is the whole section
now.

Three more places told the story of how something was built rather than what
it does. The footprint table was followed by four paragraphs on discovering
that a GraalVM image had never been compiled; the architecture tree by four on
what the second engine proved about the seam; the platforms section by a
paragraph arguing Kotlin/JS twice, once there and once again under
Architecture, where the two arguments no longer agreed. What survives of each
is the fact and the link that makes it checkable.

The status blockquote was a feature inventory, and nobody reads an inventory
to decide whether to depend on something. Scrolling, deleting, counting and
retrieving were four headings for four one-line calls and are now one.

The GraalVM row keeps its link to the CI job that produces the number, because
a claim nobody can check is worse than no claim. The two documents that linked
the renamed footprint section were repointed rather than left to 404.
@tonytonycoder11
tonytonycoder11 requested a review from a team as a code owner August 6, 2026 07:20
@trueup-by-nacode-studios

Copy link
Copy Markdown

This pull request adds no capability the code did not already have.

3 files read · 3134 ms · against d696444

@tonytonycoder11 tonytonycoder11 moved this to In progress in Kdrant Aug 6, 2026
@tonytonycoder11
tonytonycoder11 merged commit 4e57133 into main Aug 6, 2026
12 checks passed
@tonytonycoder11
tonytonycoder11 deleted the docs/readme-for-the-reader branch August 6, 2026 07:25
@tonytonycoder11 tonytonycoder11 moved this from In progress to Shipped in Kdrant Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Shipped

Development

Successfully merging this pull request may close these issues.

1 participant