A README is the sales page of your project. Here is how to write it.
Structure of a Good README¶
- Name + one-line description
- Badges (build status, coverage, license)
- Screenshot / demo GIF
- Features (bullet list)
- Quick start (3-5 steps)
- Installation
- Usage (code examples)
- Configuration
- Contributing guide
- License
Template¶
How to Write a Good README¶
One-line description of what it does.
✨ Features¶
- Feature 1
- Feature 2
🚀 Quick Start¶
npm install my-package
📖 Documentation¶
…
Tips¶
- Emojis for visual clarity (but don’t overdo it)
- GIF > screenshot > text for demos
- Quick start in 3 commands or fewer
- Code examples should be copyable (not images)
- Keep it up to date!
Test¶
Give the README to a colleague. Can they understand what the project does and how to run it in 30 seconds? If not, rewrite it.
readmedocumentationgithub