How To Write A Great GitHub README
Most GitHub repositories have a README. Very few have a good one. The difference isn't writing ability or documentation culture, it's understanding what the README is actually for. It's not a technical document. It's a conversion funnel. Every person who lands on your repository is deciding something: do I keep reading, or do I leave? That decision happens in about thirty seconds, based almost e…
- Your README is a conversion funnel, the job is to get visitors to a working result as fast as possible.
- Start with the problem, not the implementation. Earn the right to explain architecture by first proving value.
- Badges and screenshots are trust infrastructure, they answer questions visitors are silently asking before they read a word.
- Test your quick start regularly. It's the section most likely to go stale and the one with the highest conversion leverage.
The 30-Second Test Is the Only Test That Matters
Open any repository with a strong contributor base. Within the first screen, before any scrolling, you will find a clear statement of what the project does, who it's for, and why it's worth using. This isn't an accident. It's the result of understanding that attention is the scarcest resource your README has to work with. The 30-second test is simple: show your README to someone unfamiliar with the project and ask them, after thirty seconds, to tell you what the project does. If they can't, the
Structure Follows the Reader's Journey, Not the Builder's Logic
The natural instinct for an engineer writing a README is to start with what they know best: the architecture, the design decisions, the technical constraints. This is builder logic, organizing information by how it was built. Reader logic is different. Readers move from "what is this" to "can I try it quickly" to "how do I use it properly" to "how does it actually work." Structure that follows this journey converts readers into users. Structure that follows builder logic loses them at the first
Badges and Screenshots Are Trust Infrastructure
Badges, those small status indicators at the top of many READMEs, function as trust signals, not decoration. A passing CI badge tells a visitor that the code actually builds and tests pass. A license badge removes uncertainty about whether they can use this commercially. A version badge communicates that the project is actively maintained, not abandoned. These small pieces of metadata do real conversion work because they answer questions that visitors are asking before they've read a word. Scre
Frequently asked questions
- How long should a README be?
- Long enough to answer the essential questions, short enough to respect the reader's attention. For most projects, that's somewhere between 500 and 1500 words, enough for a hero statement, installation, quick start, and core usage documentation. More complex projects can justify more. The principle is that everything in the README should earn its p…
- Should a README include a contributing section?
- Yes, but it doesn't need to be long. A contributing section signals that contributions are welcome and that there's a process, both of which matter to potential contributors. The minimum viable contributing section: a statement that contributions are welcome, a link to more detailed contributing guidelines if they exist, and the key information so…
- How do you handle READMEs for projects with multiple audiences?
- Acknowledge the audiences explicitly and structure the document so each group can find what they need quickly. A common pattern is to organize by role: "For users" covers installation and usage; "For contributors" covers development setup and architecture. For projects where the audiences have very different needs, separate documentation files lin…
- What is the biggest README mistake senior engineers make that junior engineers tend to avoid?
- Writing for themselves instead of for someone encountering the project cold. Senior engineers know why the project exists, what problem it solves, and what assumptions it makes, so they skip explaining any of it. They lead with architecture diagrams and configuration reference instead of a one-sentence purpose statement and a working quick start. …
- How do you keep a README accurate as a project evolves rapidly?
- Treat the README like a test that needs to pass. The most effective pattern: add a CI job that runs the quick start commands from the README against the current codebase. If the commands fail, CI fails. This forces README accuracy because broken documentation becomes a build failure, not a deferred task. For configuration reference sections that d…