What a README has to do in its first ten seconds

A developer deciding whether to try your project gives you one screen, and they are not reading it — they are scanning it for a reason to stop.

The first screen is the whole pitch

Open your own README and stop at the fold. Whatever is above that line is what most people will ever read of your documentation. Everything below it is for the minority who have already decided to stay.

That is not a complaint about attention spans. Someone evaluating a library has four tabs open and is comparing you against three alternatives and the option of writing it themselves. They are not looking for reasons to adopt — they are looking for reasons to eliminate, because elimination is faster. A reader who cannot tell what your project is in a few seconds has found one.

The useful question is not "is my README good". It is "what does someone understand after the first screen, and is that the thing I would want them to understand".

What an evaluator is actually looking for

Three things, roughly in this order.

What it is. Not what category it belongs to — what it does. "A toolkit for modern data workflows" tells a reader nothing they can act on. "Runs your dbt models against a local DuckDB copy so tests finish in seconds" tells them whether to keep reading.

Whether it is for them. Language, runtime, and the shape of the problem. Most projects bury this in a badge row, which is the one part of a README that readers have learned to skip.

Whether it works. A runnable example earns more trust than any amount of prose about design philosophy, because it is checkable. The example does not need to be impressive. It needs to be real, short, and above the fold.

Notice what is missing from that list: the architecture, the motivation, the comparison table, the roadmap. All of those are worth writing. None of them belongs in the first screen.

The mistakes that cost the most

• Context before the example. The single most common structural problem. Several paragraphs of background sit where a reader expected to see the thing working.
• A description written for people who already know. Projects are usually described by their authors in the vocabulary of the problem they personally had. That vocabulary is invisible to the author and opaque to everyone else.
• Installation without a first run. npm install thing answers a question nobody asked. The question was what happens next.
• Badges as the first content. A row of shields pushes the sentence that matters below the fold, and conveys roughly nothing that a reader is deciding on.

Each of these is easy to fix and almost impossible to see in your own writing, for the same reason you cannot proofread your own prose: you are reading what you meant.

How to tell whether yours delivers it

Three checks that cost nothing.

Read only the first screen and write down, in one sentence, what the project does. If the sentence needs a word that does not appear on that screen, the screen is not doing its job.

Give it to someone who does not know the project and ask them who it is for. Not whether they like it — who it is for. Vagueness in their answer is vagueness in your positioning, not in their reading.

Count how far down the page the first runnable command appears. If it is below the fold, ask what is above it and whether that content is earning its place.

None of this requires a rewrite. Most READMEs that fail the ten-second test are not badly written — they are ordered for someone who already cares, and they are read by someone who does not yet.