docs: rewrite the README as a landing page - #6
Merged
Merged
Conversation
The README read as a manual: 186 lines / 1273 words, of which Secrets alone
was 62 lines and 489 words — 38% of the document, more than Why + Status +
Install combined. A backend-selection matrix containing a D-Bus error string
sat where every visitor had to scroll past it.
Benchmarked against the READMEs of comparable projects (bruno, yaak, zed,
helix, posting, atuin, httpie, ripgrep, bat, hoppscotch). Two archetypes
emerged: CLI tools whose README *is* the manual (bat 4.6k words, ripgrep 2.9k),
and GUI apps whose README is a landing page and whose docs teach (yaak 494,
zed 298, posting 256, helix 195). Posel has a GUI and a docs/ directory, so
it's the latter; it was sitting at 2.6x yaak.
Now 127 lines / 624 words. Changes:
- Leads with one claim instead of four, then three standalone sentences
ending on an absolute ("Not now, not later") — the line people quote.
- Shows a real request file inline: examples/github-api/User/get-a-user.toml,
byte-identical, variables and assertions visible in 13 lines. "Your
requests are files" is abstract; the snippet is not, and no comparable
project does this.
- Surfaces what was undersold: tRPC (the repo description already advertised
it, the README didn't), assertions + `posel-cli test`, OpenAPI/curl import,
codegen.
- Adds a "Why shouldn't I use Posel?" section — pre-1.0, unsigned builds, no
Postman-collection import. Preempts the first comment on any launch thread.
- Four badges: CI, release, license, Rust. No star or download counts.
- Moves Secrets to docs/SECRETS.md (6 lines remain), the crate table to
CONTRIBUTING.md, and build/GPUI notes there too.
Adds CONTRIBUTING.md, which the repo didn't have: build, Linux prerequisites,
crate layout, the gpui pin rationale, and the CI gate to run before pushing.
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 read as a manual rather than a pitch. 186 lines / 1273 words, of which Secrets
alone was 62 lines and 489 words — 38% of the document, more than Why + Status + Install
combined. A backend-selection matrix containing a D-Bus error string sat where every visitor had
to scroll past it.
Now 127 lines / 624 words.
How the target was chosen
I benchmarked the actual READMEs of comparable projects rather than guessing. Two archetypes:
Posel has a GUI and a
docs/directory, so it's the second kind — and was sitting at 2.6× yaak(18.9k stars, 494 words) and 1.5× bruno.
Changes
requests are files." followed by three standalone sentences ending on an absolute — "No account,
no sync server, no telemetry. Not now, not later." Bruno's equivalent "ever" is the most-quoted
word in that repo.
tomlblock that is byte-identical toexamples/github-api/User/get-a-user.toml, with{{variables}}and[[assertions]]visible."Your requests are files" is abstract; the snippet isn't. No comparable project does this — it's
the ripgrep-benchmark-table move: prove the claim instead of asserting it.
README didn't — a visitor reading both saw a contradiction), assertions +
posel-cli test,OpenAPI/curl import, codegen. Bruno gives its CLI a whole section; yaak has no CLI at all.
Stolen from ripgrep. Preempts the top comment on any launch thread.
docs/SECRETS.md(6 lines remain in the README), crate table →CONTRIBUTING.md, build steps and the gpui-pin rationale →CONTRIBUTING.md.Adds
CONTRIBUTING.md, which the repo didn't have — the cuts needed somewhere to land, andevery high-star repo in the sample links to one.
Verified
diff-identical to the real example fileposel-cli send/testinvocations run as documentedsaid "~30")
One thing to fix before this lands publicly
The v0.1.0 release is still a draft, so both the Release badge and the Download link point at an
empty Releases page. Publishing the draft (or cutting a new tag) makes the README's primary CTA
work. Everything else here is independent of that.