Skip to content

docs: rewrite the README as a landing page - #6

Merged
starvy merged 1 commit into
mainfrom
docs/readme-rewrite
Jul 21, 2026
Merged

docs: rewrite the README as a landing page#6
starvy merged 1 commit into
mainfrom
docs/readme-rewrite

Conversation

@starvy

@starvy starvy commented Jul 21, 2026

Copy link
Copy Markdown
Owner

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:

Archetype Examples Words
README is the manual (CLI, no docs site) bat, ripgrep, starship 1,395–4,654
README is a landing page (GUI app + docs/) yaak, zed, posting, helix, git-cliff 195–494

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

  • One claim, not four. Tagline is now "A native API client for REST, GraphQL, and tRPC. Your
    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.
  • Shows the file format inline. A 13-line toml block that is byte-identical to
    examples/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.
  • Surfaces what was undersold. tRPC (the GitHub repo description already advertised it, the
    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.
  • Adds "Why shouldn't I use Posel?" — pre-1.0, unsigned builds, no Postman-collection import.
    Stolen from ripgrep. Preempts the top comment on any launch thread.
  • Four badges (CI, release, license, Rust), one line. Deliberately no star or download counts.
  • Moves detail out: Secrets → 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, and
every high-star repo in the sample links to one.

Verified

  • Every relative link resolves (checked, not eyeballed)
  • The quoted toml is diff-identical to the real example file
  • posel-cli send / test invocations run as documented
  • Counts corrected against the repo: 36 requests, 7 collections, 2 environments (README previously
    said "~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.

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.
@starvy
starvy merged commit ab8d672 into main Jul 21, 2026
0 of 3 checks passed
@starvy
starvy deleted the docs/readme-rewrite branch July 21, 2026 20:14
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