A good README opens with what the project does and who it is for, then gives each type of reader the section they came for. Match the sections to the project type and format everything for skimming.
Start with what it is, not how to install it
The first thing a visitor needs is a one or two sentence answer to “what does this do and is it for me”. Do not open with a badges row or an install command. A stranger landing on your repository has not decided to use it yet, so earn that decision first.
Write the description like you are explaining it to a colleague, not like you are pitching it. “A CLI tool that snapshots a directory before a risky refactor” tells someone exactly what they are looking at. “A powerful, next-generation snapshot solution” does not.
Match the sections to the kind of project
A README for an app is not the same shape as one for a library, a CLI tool, or a backend service, and treating them the same is the fastest way to end up with padding.
- An app or web project needs features, getting started, and usage, because the reader is going to run it themselves.
- A library needs an install command and a quick usage example first, because the reader is going to depend on it from their own code.
- A CLI tool needs install plus real example commands, because the reader wants to see the exact syntax before they touch it.
- An API or backend service needs setup, environment variables, and key endpoints, because the reader is going to run and configure it, not just read it.
If a section does not serve the reader for your specific project, leave it out. A short, accurate README beats a long one padded with sections copied from a template.
Do not invent specifics you do not have yet
It is tempting to fill a README section with a plausible-looking install command or environment variable name just to make it look finished. Do not. A README that confidently states the wrong command is worse than one that is honest about a gap.
Where you genuinely do not have the detail yet, write an inline placeholder directly in the markdown so it is obvious what still needs filling in:
That placeholder is easy to find and replace later, and it does not mislead anyone who reads the README before you get back to it.
Format for skimming, not reading
Almost nobody reads a README top to bottom. They scan headings, look for a code block, and copy the first command that looks relevant. Use a single top-level title, clear ## section headings, fenced code blocks with a language tag so syntax highlighting works, and bullet lists for anything that is a list of things rather than a narrative.
Common mistakes
- Opening with a long paragraph of context before the first heading. Get to the point in one or two sentences.
- A features list of adjectives (“fast, flexible, powerful”) instead of concrete things it actually does.
- Copying every section from a template regardless of project type, so a library ends up with a “Getting Started” section written for end users.
- A code block with no language tag, or one with the wrong language tag, which breaks syntax highlighting on GitHub.