Durable Docs Avoid Opponent-Shaped Claims
Durable docs avoid opponent-shaped claims
Docs age badly when they depend on everyone else staying still.
"No maintained crate exists" might be true on the day it is written. It can
become false the next morning. It also makes the README sound more interested
in winning a comparison than helping the reader decide whether the package
fits.
Durable package docs describe the contract instead:
- what the crate owns
- what it deliberately leaves to callers
- what stable spec or behavior anchors it
- what users can verify with examples, tests, and conformance data
- where the original app still adds product policy
Competitor research still belongs somewhere. It helps decide whether a package
should exist. But the public README should not need the rest of the ecosystem
to hold still in order to remain true.
The better shape
Write this:
This crate parses Gmail-style email search syntax into a typed AST. It does
not execute the query, and it does not try to make every backend behave like
Gmail.
Not this:
No Rust email project has this yet.
The first claim is a contract. The second is a market snapshot pretending to be
a product promise.
Where this came from
The Mxr Extracted Crates README pass caught this in the extracted crate
docs. mail-query and the other package READMEs needed language that would
still be useful after another maintainer ships something adjacent.
That was not just tone polish. It changed the docs rule: public package docs
should make the user's decision easier even when the market has changed.
Comparison pages should explain lineage and trade-offs
The Spotuify comparison pages added another version of this rule. A useful
comparison does not need to turn the older project into an opponent. It can say
what the new project inherited, which boundary it moved, and what that change
cost.
The durable shape is:
- Name the work you inherited.
- Explain the architectural choice that made a new project necessary.
- Show what that choice enables with real commands or behavior.
- Say where the earlier project is still the better fit.
- Date facts that depend on a release, command count, or packaging matrix.
For spotuify, the stable claim is not that it has more features than ncspot or
spotify-player. The stable claim is that playback and reusable state belong to
the daemon, while the TUI, CLI, MCP server, and macOS app are clients. ncspot is
still simpler and more mature. spotify-player is still more configurable and
easier to use without committing to a daemon. Those trade-offs help a reader
choose. A feature-count victory would only invite the next release to make the
page wrong.
This is a standing-on-shoulders form of differentiation. Credit and honesty do
not weaken the case for a new project. They make the actual design difference
easier to see.