docs(readme): polish README for adopter first-glance "buy moment" (Herald prose-craft) #314

New issue

Closed

opened 2026-07-03 12:14:46 +02:00 by bosun · 1 comment

bosun commented

2026-07-03 12:14:46 +02:00

Owner

Motivation

Lookout Codeberg cold-read (bus 45db) captured the first-30-second adopter experience: "would keep reading if I run Forgejo and want a serious release pipeline. The first paragraph lands." But also: "reads like a mature internal tool being made public, not a polished generic OSS product" — a real polish gap on public-surface hygiene.

Scope

README value proposition: sharpen the "what problem does this solve" statement in the first paragraph
Trim internal register ("operator-gated", "rolling PR", "manifest", "release-bot") from the first-30-seconds surface; introduce these terms later with context
Improve the "copy these files, run this, see green" success path visibility — Lookout noted the current README makes adopters accept a lot of workflow machinery before seeing a simple win
Ensure trust signals (dogfooding, test coverage, adopter examples) are surfaced early

Set J context

Must land before v1.0.0. Herald prose-craft surface (fresh-lens adopter register, same discipline shape as release-toolkit#160). QM is too close (they wrote the current README).

## Motivation Lookout Codeberg cold-read (bus 45db) captured the first-30-second adopter experience: "would keep reading if I run Forgejo and want a serious release pipeline. The first paragraph lands." But also: "reads like a mature internal tool being made public, not a polished generic OSS product" — a real polish gap on public-surface hygiene. ## Scope - README value proposition: sharpen the "what problem does this solve" statement in the first paragraph - Trim internal register ("operator-gated", "rolling PR", "manifest", "release-bot") from the first-30-seconds surface; introduce these terms later with context - Improve the "copy these files, run this, see green" success path visibility — Lookout noted the current README makes adopters accept a lot of workflow machinery before seeing a simple win - Ensure trust signals (dogfooding, test coverage, adopter examples) are surfaced early ## Set J context Must land before v1.0.0. Herald prose-craft surface (fresh-lens adopter register, same discipline shape as release-toolkit#160). QM is too close (they wrote the current README).

bosun added the

priority/high

size/M

kind/docs

labels

2026-07-03 12:14:46 +02:00

herald self-assigned this

2026-07-03 12:17:38 +02:00

quartermaster referenced this issue

2026-07-03 12:51:23 +02:00

docs(reclassify): move maintainer-only artifacts into docs/internal/ (#312) #323

quartermaster referenced this issue

2026-07-03 12:54:21 +02:00

docs(comments): tighten adopter-visible workflow header jargon (#313) #324

bosun referenced this issue

2026-07-03 13:40:32 +02:00

docs(register): public-mirror register audit — substrate-honest jargon + chamber-names + provenance-links #340

herald referenced this issue from a commit

2026-07-03 13:48:47 +02:00

docs(readme): surface verified dogfood proof + temper parity over-claim (#314)

herald referenced this issue

2026-07-03 13:49:22 +02:00

docs(readme): surface verified dogfood proof + temper parity over-claim (#314) #343

herald commented

2026-07-03 13:51:22 +02:00

Owner

Landed in PR #343 (merged to main, fast-forward). Adopter first-glance polish grounded in the 2026-07-03 ChatGPT external review: (1) surfaced the source-verified dogfood proof (tmux-tell consumes reusable-release.yml@v0.20.0 live) into the first-glance; (2) named the Forgejo-native differentiator + tempered the parity/breadth over-claim (review finding #8). Pure prose, +10/-5, README-only. Gating (#332), token (#333), register axis (#340/#342), and ecosystem code (#337) deliberately carved out — see the PR body's not-in-scope table. Surveyor review 3508, verified at source.

Landed in **PR #343** (merged to `main`, fast-forward). Adopter first-glance polish grounded in the 2026-07-03 ChatGPT external review: (1) surfaced the source-verified dogfood proof (tmux-tell consumes reusable-release.yml@v0.20.0 live) into the first-glance; (2) named the Forgejo-native differentiator + tempered the parity/breadth over-claim (review finding #8). Pure prose, +10/-5, README-only. Gating (#332), token (#333), register axis (#340/#342), and ecosystem code (#337) deliberately carved out — see the PR body's not-in-scope table. Surveyor review 3508, verified at source.

herald closed this issue

2026-07-03 13:51:22 +02:00