# How to Write a Good README: Your Project's Most Important File [2026 Guide] > Your README is the front door to your project. Most developers treat it as an afterthought. Here's how to write one that actually earns trust, contributors, and users. - Canonical: https://www.kunalganglani.com/blog/write-good-readme-guide - Author: Kunal Ganglani - Published: 2026-05-01 · Updated: 2026-05-01 - Category: Developer Tools · Tags: open-source, documentation, github, developer-productivity, tutorial ## TL;DR A README is the first thing anyone sees when they visit your project — and most of them are terrible. A great README answers three questions fast: what does this do, why should I care, and how do I start using it. It's not just documentation; it's your project's front door. Get it right and you attract users and contributors. Get it wrong and nobody ever looks at your code. 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. ![Why Your README Matters More Than Your Code](https://cdn.sanity.io/images/vzekdneq/production/87bc13d5f0b755529e0c2f5982716eafca2ae9ed-1200x675.png) 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](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html)" 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](https://www.kunalganglani.com/blog/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](https://www.makeareadme.com/) 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. ![What Should a Good README Include?](https://cdn.sanity.io/images/vzekdneq/production/8b66fb0fa37cb0d406434b1e87d6ac33cbd4b2c0-1200x675.png) 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: [Watch: How To Write a USEFUL README On Github](https://www.youtube.com/watch?v=E6NO0rgFub4) ## 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. ![How to Write a README That Builds Trust Instantly](https://cdn.sanity.io/images/vzekdneq/production/52419641215ec8cd55f1c4b0be8fb370d307cb5b-1200x675.png) **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](https://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](https://mermaid.js.org/) 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](https://www.kunalganglani.com/blog/ai-generated-code-quality-crisis), 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: 1. **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. 1. **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. 1. **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. 1. **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. 1. **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](https://www.kunalganglani.com/blog/vibe-coding-tech-debt-audit), 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. Photo by De an Sun on Unsplash. ## FAQ ### What is a README file and why is it important? A README is a text file (usually written in Markdown) that introduces and explains a software project. It lives at the root of your repository and platforms like GitHub automatically display it to visitors. It matters because it's the first thing potential users and contributors see — a clear README builds trust and drives adoption, while a poor one drives people away. ### What should a good README include? At minimum, a good README should include a project title and one-line description, an explanation of why the project exists, installation instructions, usage examples, contributing guidelines, and a license. More advanced READMEs add badges for build status and coverage, screenshots or GIFs, architecture diagrams, and a table of contents. ### How long should a README be? There's no fixed length, but the key principle is scannability. A README should be long enough to answer the essential questions — what, why, and how — but structured with clear headings so readers can jump to what they need. For complex projects, consider a brief quick-start section at the top with detailed documentation below. ### Should I write the README before or after coding? Writing the README first is a surprisingly effective practice. Tom Preston-Werner, co-founder of GitHub, popularized this as 'Readme Driven Development.' Writing about your software before building it forces you to think through the design, scope, and user experience upfront — catching problems before they become embedded in code. ### How do I add badges to my GitHub README? Badges are generated through services like shields.io, which creates small status images showing build status, code coverage, package version, license type, and more. You embed them as Markdown image links at the top of your README. They provide at-a-glance project health information and signal that you actively maintain your project. ### Can I add diagrams directly to a GitHub README? Yes. GitHub natively renders Mermaid.js syntax inside Markdown files. You can write flowcharts, sequence diagrams, and other visualizations directly in fenced code blocks, and GitHub will render them as diagrams. This eliminates the need to generate and commit separate image files for architecture documentation.