I opened a GitHub repository last week. The README began with fourteen badges: build status, coverage percentage, npm version, license, downloads, and several I couldn’t identify. Below the badges was a logo. Below the logo was a tagline. Below the tagline was an installation command. There were no examples of what the library actually did or what the output looked like.
I closed the tab.
This is the front door problem. Most READMEs are front doors that don’t open: they announce that a house exists without making any effort to invite you in. The goal of a README is to take someone from “I found this” to “I understand what this is and how to start” in under two minutes. Most READMEs don’t come close.
A good README starts with what the project does, in one plain sentence. Not the vision. Not the architecture. Not the performance benchmarks. One sentence that tells a new visitor whether this is the thing they’re looking for.
Then: who it’s for. If the library is for data engineers processing streams in Python, say that. Don’t write a README that sounds like it could be for anyone, because “anyone” will skim it and leave. A specific audience feels at home faster than a generic one.
Then: a working code example with real output. Not a pseudocode snippet that shows the shape of the API. An actual example that you can copy, run, and see produce a result. Show what the input is and show what the output looks like. This is the single most effective thing a README can do to convert a visitor into a user. If the example doesn’t run exactly as shown, you’ve already broken trust.
Then: installation. The exact command. No explanation of why, no alternatives for now, no version notes unless something genuinely breaks at a specific version. Just the command.
Then: where to go next. A link to the full documentation. A link to the contribution guide. A link to the community.
Common README failures worth naming: starting with architecture diagrams before showing the use case; listing every feature before demonstrating any of them; installation steps that skip a dependency and fail silently; an example that uses variables that were never defined earlier in the README.
The README is also usually the only documentation a project has for its first year. During that period, it has to do more work than it was designed to do. That’s a reason to make it as clear as possible early, not a reason to defer it. Write it for the person who has never heard of your project and has ten other tabs open.
The Write the Docs documentation guide has useful material on writing for developers and structuring open source documentation, including READMEs. It’s worth bookmarking alongside whatever repository you’re about to document.
One more thing: the badges can go. Or at least, they can go below the first useful paragraph.