Most open-source projects die in silence. Not because the code is bad, but because the README is.
I've evaluated hundreds of GitHub repositories over fourteen years of engineering work. Reviewing them for adoption at companies, scanning them for open-source contributions, auditing them for internal tooling decisions. Every single time, the first thing I look at is the README. Not the source code. Not the issues. The README. If it's empty, vague, or a wall of unformatted text, I close the tab. So does everyone else. Learning how to write a good README is one of the highest-leverage skills a developer can build, and most of us never bother.
A README is a text file that introduces, explains, and sells your project. It lives at the root of your repository, and platforms like GitHub automatically surface it to every visitor. It answers three questions: what does this do, why should I care, and how do I use it. Get those right, and you've built the foundation for everything else — contributors, users, trust.
Your README is the beginning of your project's user experience. A bad one can be a major turn-off for potential users and contributors.
— David Oglesby, Principal Engineer at Heptio
Why Your README Matters More Than Your Code
Here's the thing nobody says about open source: your code quality is invisible until someone actually clones the repo and starts reading it. Your README quality is visible in under three seconds.
Daniel Beck, a Software Engineer who has spoken extensively on documentation practices, makes the argument that a README is an opportunity to demonstrate professionalism and empathy. It shows you care about the people who might use your work, not just the work itself. That signal matters. When I'm evaluating two libraries that solve the same problem, the one with the clear, well-structured README wins almost every time. It's not rational. It's human. If you can't explain your project clearly, why would I trust your architecture decisions?
Tom Preston-Werner, co-founder of GitHub, coined the term "Readme Driven Development" back in 2010. His argument was simple: write the README before you write any code. The act of explaining your software forces you to think through what you're actually building. More than a decade later, this advice is still underrated. I've shipped features that would have been scoped completely differently if I'd written the README first. The README isn't documentation you bolt on at the end. It's a design document that happens to also be user-facing.
For those maintaining open-source projects, this matters doubly. The open source sustainability crisis is real, and a well-crafted README is one of the few zero-cost tools that directly increases contributor retention. People contribute to projects they understand.
What Should a Good README Include?
The Make a README project provides a solid starting template covering the essentials: Installation, Usage, Contributing, and License. That's a good floor. But a README that only covers the basics is like a landing page with no value proposition. You need to go further.
Here's what a strong README actually contains, and more importantly, why each section earns its place:
Project title and one-line description. This sounds obvious, but I've seen repos where I genuinely couldn't figure out what the project did after reading the first three paragraphs. Your first line should tell me what this is and who it's for. "A lightweight CLI tool for converting Markdown to PDF" beats "Welcome to ProjectX!" every time.
The Why. Most READMEs skip straight to installation. That's a mistake. Before I install anything, I need to know why this exists. What problem does it solve? What alternatives did you consider? Two sentences here save your users twenty minutes of research.
Installation instructions. Be specific. Include the package manager command, the minimum runtime version, and any system dependencies. Don't assume everyone is on your OS. If there's a Docker option, mention it.
Usage examples. Show me the two or three most common things someone would do with your project. Keep it concrete. A single clear example is worth more than a link to full API docs.
Contributing guidelines. Even a short section signals that you welcome contributions. Link to a CONTRIBUTING.md if you have one, but put the basics in the README itself. How to run tests, how to submit a PR, what the code style expectations are.
License. Always include it. A project without a license is legally unusable in most corporate environments. MIT, Apache 2.0, GPL — pick one and state it clearly.
Here's a video walkthrough that covers these fundamentals well:
[YOUTUBE:E6NO0rgFub4|How To Write a USEFUL README On Github]
How to Write a README That Builds Trust Instantly
Beyond the essentials, there's a layer of README craft that separates good projects from the ones that actually get adopted. These are the details that build trust before someone writes a single line of integration code.
Badges. Those little colored shields at the top of a README — build passing, coverage percentage, npm version, license type — aren't decoration. According to shields.io, which powers most of them, badges provide live, at-a-glance information about a project's health. A green "build passing" badge tells me this project has CI. A coverage badge tells me someone cares about testing. I've worked on teams where the presence or absence of badges was literally part of the library evaluation checklist.
Screenshots or GIFs. If your project has any visual component — a CLI with colored output, a web UI, a mobile app — show it. A three-second GIF communicates more than ten paragraphs of description. Tools like asciinema for terminal recordings or simple screen captures go a long way.
Architecture diagrams. For anything more complex than a single-purpose utility, a high-level architecture diagram pays for itself immediately. GitHub now natively renders Mermaid.js syntax in Markdown files. That means you can embed flowcharts, sequence diagrams, and entity-relationship diagrams directly in your README without generating external images. No extra build step, no stale PNGs. Just write the Mermaid syntax in a fenced code block and GitHub renders it. I've started using this for every project with more than two components. The drop in "how does this work?" questions has been noticeable.
A table of contents. If your README is longer than a few screen heights, add one. Markdown doesn't have native TOC support, but GitHub auto-generates anchor links for headers. A simple bulleted list at the top linking to each section makes your README navigable instead of scrollable.
If you've dealt with AI-generated code quality issues, you know how important clear documentation is for codebases that may have been partially generated. A strong README is your first line of defense against confusion.
The 5 README Mistakes That Kill Open-Source Projects
After reviewing hundreds of repositories, both professionally and as an open-source contributor, I see the same mistakes constantly. These are the ones that actually cost projects users and contributors:
The empty README. Just a project name and nothing else. This is the equivalent of opening a restaurant with no sign, no menu, and the lights off. GitHub will still surface this file. It'll just surface your indifference.
The "obvious to me" README. Installation instructions that assume you already know the project's ecosystem. "Run
make install" with no mention of dependencies, build tools, or supported platforms. What's obvious to you after six months of development is completely opaque to a first-time visitor.The novel. Ten thousand words, no headers, no structure, no visual hierarchy. The Make a README project makes this point well: a README should be scannable. Engineers don't read documentation linearly. They scan for the section they need. If your README is a single block of prose, nobody is reading it.
The outdated README. Installation instructions referencing a deprecated API. Screenshots of a UI redesigned two versions ago. Config examples that throw errors on run. An outdated README is worse than a missing one because it actively misleads people. I once spent forty minutes debugging a setup issue that turned out to be a README pointing to a config format the project had abandoned months earlier. Forty minutes I'll never get back.
The "see the docs" README. A single line: "For documentation, visit our wiki." And the wiki is either empty, disorganized, or requires authentication. Your README is the documentation entry point. If someone has to leave the repository to understand your project, you've already lost most of them.
Advanced README Patterns Worth Stealing
Once you've nailed the basics, here are patterns I've seen in the best READMEs across the ecosystem.
The comparison table. If your project exists in a competitive space (and most do), a brief comparison table showing how you differ from alternatives is worth the effort. Columns for features, performance characteristics, or philosophy. This isn't about trashing competitors. It's about helping users make informed decisions quickly.
The "non-goals" section. Explicitly stating what your project doesn't do is almost as valuable as stating what it does. It saves users from evaluating your tool for a use case you'll never support, and it signals architectural maturity. I've started including this in internal project docs too, and it dramatically reduces scope creep conversations.
The quick-start vs. full guide split. Give impatient users (which is all of us) a five-line quick-start at the top, then provide the detailed guide below. This respects both the "I just want to try it" user and the "I need to understand everything" user.
Versioned compatibility matrices. A table showing which versions of your project work with which versions of its dependencies. Especially critical for libraries. Nothing wastes developer time like version incompatibility surprises, and a simple table prevents hours of debugging. If you've ever dealt with vibe-coded tech debt, you know that unclear dependency documentation makes a bad situation catastrophic.
The README Is the Product
Here's my actual take: the line between documentation and product is gone. In a world where developers evaluate tools in minutes, not days, your README is the product experience. The landing page, the sales pitch, the onboarding flow, and the support document. All compressed into a single Markdown file.
I've watched projects with mediocre code but excellent READMEs outperform technically superior projects with terrible documentation. That's not a fluke. That's the market telling you something. The projects that win aren't always the best-engineered. They're the most accessible.
So here's my challenge: go look at the README of your most important project right now. Read it as if you've never seen the codebase. Does it answer what this is, why it exists, and how to use it in under sixty seconds? If not, that's your highest-impact commit this week. Not a new feature. Not a refactor. A README rewrite.
The best code in the world is worthless if nobody can figure out what it does.
Originally published on kunalganglani.com
Top comments (0)