Cut the README down to what a reader needs - #115
Merged
Conversation
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.
|
This pull request adds no capability the code did not already have. 3 files read · 3134 ms · against |
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 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.mdrestated in prose, which is the failure mode the one-home rule exists to prevent: twodescriptions 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
## Architectureargued 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.mdanddocs/migrating-from-qdrant-client.mdboth linked#footprint-vs-the-official-client, which is now#compared-with-the-official-client. Fixed hererather than left to 404.
audit-library.shreports the repository at standard, with the section order, the status blockquote andthe shipped-state vocabulary all intact.