Our README was the usual wall: a paragraph of marketing, then npm install, then nothing. New hires bounced off it constantly.
What finally worked was forcing the model to write for one specific reader (a dev who cloned the repo 30 seconds ago and has one question: how do I run this) and banning the marketing voice entirely. The "first five minutes" framing reorganized everything.
How do you keep the quickstart honest when the setup steps drift over time?
Write a README.md for the repo I will paste. Write for ONE reader: a developer who cloned this 30 seconds ago and wants it running locally in under 5 minutes. Structure, in this order:
1. One sentence: what this is and who it's for. No adjectives like 'powerful', 'simple', 'modern'.
2. Quickstart: the exact commands, copy-pasteable, assuming nothing installed beyond the language runtime. Note the prerequisite versions.
3. "Verify it worked": the one command or URL that proves the setup succeeded, and what they should see.
4. Common failure: the single most likely thing to break in setup and its fix.
5. Where to go next: 3 links max (architecture, contributing, deploy).
Rules: no emoji, no badges section, no 'Table of Contents' for a doc this short, no feature list longer than 5 bullets. Every command must be runnable as written. If a step needs a value I haven't given you, mark it {LIKE_THIS} and list all such placeholders at the bottom.The single-reader framing is the unlock. I added one line that killed the last of the fluff: "Assume the reader is slightly annoyed and in a hurry." Suddenly every sentence had to earn its place. Also: ask it to put the copy-paste block above any prose, because that's what people scan for first.
Append: Assume the reader is slightly annoyed and in a hurry. Lead each section with the runnable command or concrete artifact BEFORE any explanation.
To keep the quickstart honest as it drifts, I don't hand-maintain it. I have the model emit the quickstart as a shell script the CI actually runs on a clean container. If the README commands break, the build goes red. The doc becomes a test.