Most people who open your README are deciding whether to read it. They came from a search result, a link in an issue, or a dependency list, and they will give the page a few seconds. In that time they want three answers: what is this, is it for me, and how do I try it. A README that answers those three in its first screen does most of its work before anyone scrolls.
This article is a structure for that first screen, with an example built around a small command line tool, and the parts that belong further down. The tool, logtrim, is invented for this article; the commands show the shape of a README, not a real package.
What does a stranger need first?
Think of the reader who has never heard of the project. They do not know your internal names, the history of the repository, or why it was started. They know their own problem.
So the first screen answers, in order:
- What it does, in one sentence, in words the reader would use for their own problem.
- Who it is for, or the situation where it helps.
- What using it looks like, as the shortest real example.
- How to install it, as one command if possible.
Everything else (configuration, architecture, contributing, the changelog, the badges) is for people who already decided to stay.
The one-sentence description
The first sentence is the hardest and the most important. A useful test: could someone who has the problem recognise it in your sentence without knowing your field's vocabulary?
Weak versions describe the implementation or praise it:
A fast, modern, extensible CLI built with Rust for working with log files.
This says what it is made of and how the authors feel about it. It does not say what happens when you run it.
A stronger version describes the result:
logtrim cuts large log files down to the lines that matter: the errors and the lines around them.
The reader now knows whether this is their problem. If they do not have large log files, they can leave, and that is also a good outcome.
Show the shortest real example
After the sentence, show it working. Not a full tutorial: one input and one output, copied from a real run.
$ logtrim app.log --context 2 [12:04:11] INFO request started id=8812 [12:04:11] INFO calling payment service [12:04:12] ERROR payment service timeout after 5000ms [12:04:12] INFO retry 1 scheduled [12:04:13] INFO retry 1 ok A reader understands an example faster than a list of features, because they can see the shape of the result and compare it with their own case. Keep the example small enough to fit on the screen with the description above it. If the real output is long, cut it and say so in a comment.
Install in one line, then point onward
cargo install logtrim If installation needs more than one step, put the most common path here and link to the full instructions further down. The first screen is for trying, not for every operating system.
Before and after
Here is a typical README opening, shortened:
# logtrim [badges: build, coverage, version, license, downloads] logtrim is a modern, blazing fast log processing toolkit. It was started in 2023 to solve problems we had at work and has grown into a flexible framework with plugins, multiple output formats and a configuration system. ## Table of contents ... A stranger reads the badges, a history, and adjectives, and still does not know what the tool does to a log file.
The same opening, rewritten:
# logtrim logtrim cuts large log files down to the lines that matter: the errors and the lines around them. Useful when a log is too long to read and grep shows the error without its context. (example run) (install command) Nothing was invented. The facts were already in the old version; they were in the wrong order and hidden behind words that describe the authors rather than the tool.
What goes further down
Once the first screen is right, the rest of the README can be ordered by how often people need it:
- Usage: the common options, each with a short example.
- Configuration: only if there is any.
- How it works: a short section for people who want to trust it before they use it. A diagram helps here more than anywhere else.
- Limitations: what it does not do. This saves the reader time and saves you issues.
- Contributing, license, changelog: links are often enough.
Badges can stay, but below the description, not above it. They answer questions a stranger asks later.
A checklist for the first screen
- The first sentence says what happens when someone uses it, not what it is built with.
- No word in that sentence needs knowledge of the project to understand.
- There is one real example with real output.
- There is one install command.
- No adjectives that the reader cannot check (fast, modern, powerful). If speed matters, show a measurement further down.
- Someone who does not have the problem can tell within seconds that the project is not for them.
A quick way to check: give the README to someone outside the project, let them look for half a minute, close it, and ask them what the tool does. If their answer matches your first sentence, the first screen works.
Where this does not help
A library with a large API surface cannot show itself in one example. Show the most common call, and accept that the reference documentation does the rest.
Internal repositories have a different reader: a colleague who already knows what the service is for. For them, the first screen is better spent on how to run it locally and who owns it.
And no README fixes a project whose purpose is unclear to its own authors. If the one-sentence description is hard to write, that is often a signal about the project, not about the writing.
Write the first sentence for someone who has the problem and has never heard of you, then show one real run.
Written with the help of AI and checked by the explain.ink team.
