# Making A Great Readme > Writing an effective readme is one of the best low-lift things you can do to support the growth and health of your open source project. Here is a guide to doing that! URL: [Original article](https://mattcool.tech/posts/making-a-great-readme) Published: 2025-12-04T07:31:00.000Z Tags: opensource ## Why We Need Good READMEs Your README is often the first impression someone has of your project. A great README can be the difference between someone moving on or choosing to engage with your project. When developers land on your repo, they're asking themselves: *"Is this worth my time?"* Developers routinely make judgments within seconds, deciding whether to dig deeper or move along. A clear, well-structured README signals that the project is maintained, the author cares about the developer experience, and the barrier to entry is low. Think of it this way: you've spent hours, days, maybe months building something valuable. Don't let these efforts go to waste because your README doesn't do justice to your project. Skip to the [checklist](#tldr-checklist) and [prompt](#prompt-a-readme-consultant) at the bottom if you want a quick reference. --- ## What You Need From Top to Bottom ### 1. Project Name Make it clear and prominent. This seems obvious, but many repos bury the actual project name. --- ### 2. Visual Demo or Banner If applicable to your project, include a short GIF or image that conveys the project's value or brand. Keep it as brief as possible abd aim for under 10 seconds for GIFs. **Why its important:** People process visuals faster than text. A quick demo can communicate what paragraphs of explanation cannot. Place it right after the name as a visual hook, linking to higher quality demos doesnt hurt in my view. [Image: Example of a project banner from Jan] Caption: Example banner from Jan, an open-source offline chatbot application. (https://github.com/janhq/jan) --- ### 3. Badges Badges provide dynamic, highly relevant info about your project at a glance. **Best practices:** - **Don't use more than 5** too many badges=too much noise - **Use meaningful alt text** if the badge service is slow or down, users will see your alt text instead - **Priorities vary by project:** license, current version, build status, community stats/link... think about what matters most for project signal and what top level information readers will want to see. [Image: Example of a project banner from Jan] Caption: Example badges from NVIDIA Dynamo. (https://github.com/ai-dynamo/dynamo) --- ### 4. Table of Contents If your README is long, add a TOC to help readers navigate. ```markdown ## Table of Contents - [Quick Start](#quick-start) - [Usage](#usage) - [Getting Help](#getting-help) - [Contributing](#contributing) ``` --- ### 5. Elevator Pitch **1-2 sentences on what your project does.** Be laser-focused so people can quickly understand the value. Do your best to avoid jargon or buzzwords, even if your project is blazingly fast. ❌ *"A comprehensive solution for managing various aspects of your application's state management needs across multiple platforms and environments."* ✅ *"Dead-simple state management for React. One hook, zero boilerplate."* --- ### 6. Quick Start / Getting Started / Installation How to get your project running in **all relevant environments**. This is where many READMEs fail—they assume too much knowledge or skip steps. Run through this with contributors and members of your community who are new if they are willing. This is a great way to establish relationships with newcomers, make them feel welcome. Treat the meet like a UX research session. Dont tell them what to do or guide them, let them fail and note the friction points. **Include:** - Prerequisites (Node version, dependencies, etc.) - Installation commands - Verification that it's working - Any environment-specific notes (Windows vs. Mac vs. Linux, etc.) ```markdown ## Quick Start ### Prerequisites - Node.js 18+ - npm or yarn ### Installation \`\`\`bash npm install your-package \`\`\` ### Verify Installation \`\`\`bash npx your-package --version \`\`\` ``` --- ### 7. Usage Examples Provide basic examples with links to your docs for deeper dives or more complex use cases. **Keep examples:** - Copy-pasteable - Minimal but functional - Progressively complex (basic → intermediate → "see docs for advanced") ```markdown ## Usage ### Basic Example \`\`\`javascript import { thing } from 'your-package'; const result = thing.doStuff(); console.log(result); \`\`\` For more examples, see the [documentation](https://your-docs-site.com). ``` --- ### 8. Getting Help Direct people to the best channels for support. Community forums, Discord, GitHub Discussions, etc. **⚠️ Important:** Think about where your support lives and what you can realistically maintain long-term. Be very transparent about support expectations. **Support is a marathon, not a sprint.** Responsiveness is critical to a project's health. Take a moment to note how Blender's community grew as their response times improved: [Image: Chart showing Blender] Caption: Blender's commitment to fast response times directly correlated with their community growth. Quick, helpful responses build trust and encourage contribution. --- ### 9. Links to Supporting Docs End your README by linking to the important supporting documents: #### CONTRIBUTING.md Guidelines for how others can contribute to your project. Include coding standards, PR process, and how to set up a development environment. #### LICENSE The legal terms under which your project can be used, modified, and distributed. Choose one that fits your goals (MIT, Apache 2.0, MPL, etc.). #### CODE_OF_CONDUCT.md Sets expectations for community behavior. This is important if you are running a community. The [Contributor Covenant](https://www.contributor-covenant.org/) and [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) are popular choices for inspiration. #### ROADMAP.md Share your vision for the project's future. Helps contributors understand priorities and find meaningful ways to help. #### AGENTS.md Instructions for AI coding agents (like GitHub Copilot, Cursor, or Claude) on how to work with your codebase. Include project structure, conventions, and context that helps AI tools generate better code for your project. --- ## TL;DR Checklist --- ## Prompt a README Consultant Want help improving your README right now? Copy the prompt below into your favorite AI assistant, then paste your current README when asked.