A README is the first — and sometimes only — thing anyone reads before deciding whether to use your project, contribute to it, or close the tab. Yet it's routinely the most neglected file in a repository, often a single unformatted paragraph written in the last five minutes before a first commit. Here's what actually makes one useful.
Lead with what it does and why, in one or two sentences
The single most common README mistake is burying the answer to "what is this?" beneath a badge collection, a table of contents, and a lengthy backstory. A reader deciding whether to keep reading needs that answer in the first ten seconds. State plainly what the project does and, ideally, what problem it solves — not how it's implemented.
A structure that works for most projects
- Title and one-line description. What it is, immediately.
- A short "why." One or two sentences on the problem this solves, especially if the name alone doesn't make it obvious.
- Installation. The exact commands to get it running, assuming nothing about what the reader already has installed.
- A minimal usage example. The smallest possible example that actually does something, not a contrived "hello world" that doesn't reflect real use.
- Configuration (if applicable). The options someone will actually need to touch, not an exhaustive dump of every internal setting.
- Contributing. Even a single sentence pointing to a CONTRIBUTING file or issue tracker signals the project is open to input.
- License. Which one, stated plainly — this single detail determines whether companies and other projects can even consider using your code.
Write the installation steps for someone who has nothing set up
"Just run npm install" assumes the reader already has Node installed, already cloned the repo, and already knows to run the command from the right directory. Write installation instructions assuming none of that. This sounds like over-explaining until you remember that a meaningful fraction of your readers are evaluating whether your project is worth the effort at all — friction here loses people who would otherwise have used it.
Show, don't just tell, with a real example
A code block demonstrating actual input and output does more to communicate what a project does than a paragraph of description. If your project is a command-line tool, show the exact command and what it prints. If it's a library, show a minimal but realistic usage snippet — not an abstract stub with placeholder variable names that don't map to anything concrete.
Badges: use sparingly
Build status, version, and license badges are useful at a glance, but a wall of a dozen badges above the fold pushes the actual description further down the page — exactly the information the reader needs first. Two or three meaningful badges communicate more than ten decorative ones.
Keep it maintained, or say so explicitly
A README describing setup steps that no longer work, or referencing a version that's long since changed, actively damages trust in the project. If you can't keep it perfectly current, a one-line note ("actively maintained" vs. "in maintenance mode, PRs welcome but slow to review") sets honest expectations and costs you nothing.
This guide reflects our own practice writing documentation for open-source and internal tools.