How to write a README that makes people try your project
George · 2 min read
The short answer: the first screen of your README should say what the project does in one sentence, show it working with a screenshot or short clip, and give the fastest way to try it. Everything else, such as configuration, details and contributing, comes after. Write it for someone who has never heard of you and has thirty seconds.
For developer tools and open source projects, the README is the landing page. Most visitors decide whether to try your project before they scroll. AI assistants increasingly read it too, when someone asks them which tool to use.
The first screen
Someone landing on your repository should see, without scrolling:
- The name and one sentence saying what it does and for whom. "A command line tool that resizes images for every app icon size" beats "A powerful, flexible image toolkit".
- A picture of it working. A screenshot, a short animated clip, or the output of a command. Seeing it run is the strongest argument you have.
- The quickest way to try it. One install command, or a link to a live demo.
A structure you can copy
- What it is in one or two sentences.
- Screenshot or demo.
- Quick start: install and the smallest working example.
- Features: a short list of what it does, in plain words.
- Usage: common tasks with examples you can copy.
- Configuration: options, with defaults.
- Limitations: what it does not do yet. This builds trust.
- Contributing and license.
Make the quick start really quick
Test your quick start on a clean machine or a fresh account, exactly as written. Missing steps that feel obvious to you, such as a required version of a language or an environment variable, are the most common reason people give up. If something needs a key, say where to get one.
Write examples people can copy
Show real commands and real output. Use names that look real, not foo and bar. Keep each example small and focused on one task, so people can copy it, change one thing, and see it work.
Keep it honest and current
List requirements and limits plainly. Remove features you dropped. Update the screenshot when the interface changes. An out-of-date README makes a project look abandoned even when it is not.
Link to where it lives
If your project has a website, docs or a launch page, link to them near the top. A launch page with a description, screenshots and comments gives people another place to discover your project and talk about it.
The short version
- First screen: one sentence, a picture of it working, the quickest way to try it.
- Test the quick start on a clean setup.
- Use small, realistic examples.
- Be honest about limits and keep it current.
- Link to your site and launch page.