Readme that sells

readme-that-sells

Rewrite a README with someone whose project deserves better than the default one. The README is the landing page of their work — recruiters, teachers, and other developers will judge the project by it before reading a line of code. They write the words; you know what a visitor needs and in what order. The rewritten README is pushed by the end of the sitting.

Read the project first

Before touching the README, read the actual repo: what the code does, how it runs, what state it is in. The README must match reality. Then ask them the visitor questions and make them answer out loud:

• What does this do, in one sentence a non-user understands?
• Why did you build it? The real reason — "my bus is always late" is a better opening than any mission statement.
• What works today, and what is half-built or planned?
• How does someone run it on their machine, exactly?

Their spoken answers are the raw material. Write down what they said, not what a README "should" sound like.

The 10-second test

Order matters more than polish. A visitor gives the page seconds:

1. Name and the one-liner. Plain words. "Tracks the 42 bus in real time" beats "A revolutionary transit solution."
2. A screenshot, GIF, or live link if the project has a face. This is the highest-value item on the page; help them capture one now, not later.
3. Why it exists — two or three sentences, their story.
4. How to run it — commands they have actually re-run from a clean clone in this session. A README whose install steps fail is worse than no README.
5. What's real: works / rough / planned, honestly labeled. Honest scope reads as competence; a stranger can smell overclaiming.

Skip the badge wall, the empty "Contributing" boilerplate, the license essay (one line and a LICENSE file is plenty), and any section with nothing true to say.

Language pass

Go through their draft line by line. Cut every unverifiable adjective — powerful, seamless, blazing, robust. Cut sentences that describe no feature and make no claim a visitor can check. Watch for machine-writing tells: triple lists for rhythm, "it's not just a tracker, it's a platform" constructions. If the project is small, the README should be short. Short and true is the goal.

Ship

• They run the install steps themselves from a fresh clone, top to bottom. Fix the README (or the code) until the steps just work.
• Commit and push. Check how it renders on GitHub — formatting, image, links.
• Send the repo link to one person who has never seen the project and ask what they think it does. If the answer misses, the one-liner gets another pass.

Done

• README states what the project does, shows proof, and labels current limitations
• Setup commands pass from a fresh clone on a documented environment
• Public rendering, media, and links are checked; an unfamiliar reader can state the project's purpose accurately

If this project belongs on their resume, the build-resume skill will want the one-liner they just wrote.