Your GitHub README is the front door of your project. It's the first thing people see when they land on your repo — and most of them leave within 30 seconds if it doesn't answer three questions immediately:
What does this do? Why should I care? How do I get started?
Most READMEs answer none of these clearly. Here's how to fix that.
The anatomy of a great README
A good README has six sections, in this order:
# Project Name
One-line description that explains what it does and who it's for.
## Why this exists (optional but powerful)
What problem does this solve? Why did you build it?
## Quick Start
bash
npm install your-package
your-package --input file.txt
## Features
- Bullet list of what it can do
- Keep it specific, not vague
## Documentation
Link to full docs, or cover the main API here
## Contributing
How to submit issues and PRs
markdown
The most common README mistakes
1. No quick start. The most visited section of any README is the installation/usage section. If you bury it or link somewhere else, you lose people. Put a working code snippet in the first 20 lines.
2. Vague descriptions. "A powerful tool for developers" tells me nothing. "Converts CSV files to JSON in one command" tells me everything. Be specific.
3. Outdated badges. Broken CI badges or "build: failing" signals abandonment. Either fix them or remove them.
4. No screenshot or demo. If your project has a UI, show it. A GIF is worth a thousand words of documentation.
5. Writing for yourself, not the reader. You know how your project works. Your reader doesn't. Write for someone opening it for the first time.
What a bad README looks like (and why)
"This README has the energy of someone who built something great and then described it to their mum over the phone. The Installation section reads like a choose-your-own-adventure where all paths lead away from this file."
Sound familiar? Even major open source projects get this wrong. The fix is usually simple: add a 3-line quick start, rewrite your first paragraph to be specific, and remove anything that's broken or outdated.
A README template you can copy
# Tool Name — tagline in one sentence
[] []
**What it does:** One sentence. Specific, not vague.
## Quick Start
bash
npm install tool-name
tool-name --input example.csv --output result.json
## Why use this over alternatives?
- Faster than X because Y
- Works with Z out of the box
- No configuration needed for common cases
## Installation
Full installation instructions here...
## Usage
js
const tool = require('tool-name')
tool.run({ input: 'file.csv' })
## Contributing
PRs welcome. See CONTRIBUTING.md.
## License
MIT
Get instant feedback on your README
Not sure if your README is actually good? Get it roasted by AI — you'll know within 30 seconds what's wrong and what to fix.
🔥 Roast My README — Get your README brutally roasted by AI. Free preview, $2 for the full report.
Originally published at https://conker.tools/blog/how-to-write-a-good-github-readme
