Most READMEs fail in the first ten seconds — before anyone reads a word, because there’s no way to tell what the project does or whether it’s worth their time. A README’s job is to get someone from “found this on GitHub” to “running it locally” in under two minutes. Five sections, in this order, do that.

1. What it is, in one sentence, above the fold

Not your project’s philosophy. Not a badge wall. One sentence that says what it does and who it’s for:

# reqcache

A drop-in HTTP response cache for Node.js APIs — Redis-backed,
zero config for the common case.

Compare that to the version most projects ship:

# reqcache

reqcache is a powerful, flexible caching solution built with
performance and developer experience in mind.

The second one tells you nothing. “Powerful, flexible” is true of every library ever published and communicates zero information about what problem it solves or who should reach for it.

2. The demo, immediately after

Before install instructions, before a feature list — show it working. A GIF of the terminal output, or a code block someone can paste and see run:

const { cache } = require('reqcache')

app.get('/api/users', cache('5m'), (req, res) => {
  res.json(await db.users.findAll())
})
// second request within 5 minutes returns from Redis, ~1ms

This is the section that actually sells the project. Nobody decides to try your tool from a features list — they decide from seeing five lines of code and immediately understanding what changes if they use it.

3. Install, copy-pasteable, no filling in blanks

npm install reqcache

That’s the whole section if it’s really one command. Don’t pad it with prose about peer dependencies unless there genuinely are optional ones, and if there are, put them in a collapsed <details> block, not inline — most readers don’t need them and they push the important stuff further down the page.

4. Usage, the common case only

Cover the 80% case with working code, not every configuration option:

const { cache } = require('reqcache')

cache('5m')                          // 5 minute TTL, default key
cache('5m', { key: req => req.url }) // custom cache key
cache('5m', { redis: myRedisClient }) // bring your own Redis client

Link to a separate docs/ folder or wiki for the full config reference. A README that tries to document every option becomes unreadable, and the person deciding whether to try your project doesn’t need option #14, they need to see the common path work.

5. Status and support, honestly

## Status
Stable, used in production. Maintained in spare time — see
SUPPORT.md for response-time expectations.

## License
MIT

This section is small and most people skip writing it, which is exactly why it stands out when it’s there. It answers the two questions a serious adopter actually has before depending on your code: is this maintained, and what am I allowed to do with it.

What to cut

Badge walls with a dozen shields before any content. A “Table of Contents” for a README under 200 lines — if it needs a table of contents to navigate, the README is too long, not under-organized. A “Motivation” essay before the demo — save your reasoning for a blog post or a docs/motivation.md, it doesn’t belong between the title and the thing that proves the project works.

The test

Show your README to someone who’s never seen the project and time how long it takes them to understand what it does and paste a command into their terminal. Under a minute is a working README. If it takes longer, the demo section is either missing or too far down the page — that’s almost always the actual fix, not more explanation anywhere else.