README Writing Guide — GitHub Project Documentation
A README is the front door of your GitHub project. It determines whether developers will use your library, contribute to your project, or move on. This guide covers the essential sections, recommended lengths, and best practices for writing READMEs that attract users and contributors.
Essential README Sections
| Section | Recommended Length | Purpose |
|---|---|---|
| Project title + badges | 1–2 lines | Name and status at a glance |
| Description | 2–4 sentences (30–60 words) | What the project does and why |
| Quick start / Installation | 50–150 words | Get running in under 2 minutes |
| Usage examples | 100–300 words | Common use cases with code |
| API reference | Varies | Function signatures and parameters |
| Contributing | 50–100 words | How to contribute |
| License | 1 line | License type |
The 30-Second Rule
A developer should understand what your project does within 30 seconds of opening the README. This means the description and quick start must be immediately visible without scrolling. Lead with a one-line description, then a code example showing the simplest use case.
Code Examples
Include at least one copy-pasteable code example in the first screenful. Use fenced code blocks with language identifiers. Show the minimal working example first, then link to more complex examples in a docs folder or wiki.
Badges
Badges (build status, coverage, npm version, license) provide instant project health signals. Place them right after the title. Limit to 4–6 badges — too many create visual noise.
Common Mistakes
- No installation instructions — Never assume users know how to install your project.
- Outdated examples — Code examples that don't work destroy trust instantly.
- Wall of text without structure — Use headings, code blocks, and lists for scannability.
Conclusion
A good README has a clear description (30–60 words), quick start (50–150 words), and usage examples (100–300 words). Use Character Counter to check your section lengths.