Most READMEs are written by the person who knows the project best, at the moment they know it best. That is exactly why so many of them are hard to use. The author no longer remembers what it felt like to arrive with no context.
A reader landing on a README usually has three questions, in this order:
- What is this?
- Is it for me?
- How do I get it running?
If the first screen answers those three, the README is already better than most. Everything else can come later.
Lead with what it does, not what it is built with
The opening line is the most valuable space in the file, and it is often spent on the wrong thing.
Before:
A lightweight, blazing-fast, TypeScript-first, zero-dependency solution leveraging modern APIs.
After:
Converts Markdown files into a static website. Runs from the command line, needs no configuration for simple sites.
The first version lists qualities. The second describes a result. A reader can decide in five seconds whether the second one solves their problem. With the first, they still have to guess.
Adjectives like "lightweight" or "fast" are not wrong, but they are claims. Put them after the description, and ideally back them up with something the reader can check.
Say who it is not for
This feels counterintuitive, but it saves everyone time. A short line such as "This tool is not designed for sites with more than a few hundred pages" or "Requires Node 20 or later" helps the wrong reader leave early and the right reader stay with confidence.
Limits are information. Leaving them out does not make a project look more capable; it just moves the disappointment to later, usually into the issue tracker.
Make the first steps copyable
The installation section should be something a reader can follow without thinking. That means:
- Real commands, in code blocks, in the order they are run.
- One path first. If there are four ways to install, show the most common one and link the rest further down the same file.
- A visible result. End the section with what the reader should see when it worked, for example the expected output or the address to open in a browser.
That last point is the one most often missing. Without it, the reader finishes the steps and still does not know whether they succeeded.
Keep the order of the reader, not the order of the code
READMEs often grow in the order features were added. The result is a file where configuration options appear before the basic usage, or a contribution guide sits between installation and the first example.
A simple order that works for most projects:
- One-sentence description
- Who it is for, and key limits
- Installation
- A minimal working example
- Common tasks
- Configuration reference
- Contributing and licence
Read only the headings of your README. If they do not follow roughly the path a new user takes, reorder them.
Write the example you would want
One small, complete example is worth more than a long list of options. Complete means it can be copied, run and understood without reading anything else. Avoid placeholders that need explanation, such as <your-thing-here>, unless the explanation sits directly next to them.
If the example needs a file, show the file. If it needs a setting, show the setting. The reader should never have to assemble the example from three different sections.
Review it as a stranger
The best test is simple: give the README to someone who has never seen the project and watch where they hesitate. If that is not possible, wait a few days and read it again yourself, top to bottom, following every step literally.
Each place you have to stop and think is a place a new reader will stop and leave. Fix those first. Polish can wait; clarity cannot.
Top comments (0)