A GitHub README is the first thing anyone sees when they find your project. It has about 10 seconds to answer: What does this do? Why should I care? How do I use it? If it doesn't answer all three quickly, most visitors leave.
I've reviewed hundreds of open source projects. The READMEs that keep me reading share the same structure. The ones that lose me share the same mistakes.
The essential sections
Title and description: One line. What does this project do? Not how it works, not why you built it, not the technology stack. What does it do for the user? "A fast JSON parser for Node.js" is good. "This project was created as a learning exercise in parsing algorithms" is a project diary, not a README.
Installation: Copy-pasteable commands. Not "install it using your package manager." The actual command: npm install your-package. If there are prerequisites, list them before the install command.
Quick start: Three to five lines of code that demonstrate the basic use case. This should work as-is if someone copies it after installation. No complex configuration, no environment setup, just the simplest possible working example.
API documentation: For libraries, every public function needs its signature, parameters, return value, and a brief example. For CLI tools, every command and flag.
Contributing: How to set up the development environment, run tests, and submit changes. Projects without contributing guidelines don't get contributions.
License: The full license text or a link to it. No license means "all rights reserved" by default, which means no one can legally use your code.
Common mistakes
Starting with badges. A row of twenty badges (build status, coverage, downloads, license, dependencies) before any description of what the project does. Badges are secondary metadata. Lead with content.
No code examples. Describing what a library does in prose instead of showing it in code. Developers read code faster than documentation. Show them a 5-line usage example and they'll understand what your project does immediately.
Outdated information. A README that describes a different version of the API than what's currently published. This is worse than no README because it actively misleads. Automated tools like documentation generators help, but someone needs to verify accuracy on major releases.
Assuming context. "Install Redis and configure the connection" assumes the reader knows what Redis is, has it installed, and knows how to configure it. If Redis is a dependency, provide the install command and the minimum viable configuration.
README template structure
# Project Name
One-line description of what it does.
## Installation
npm install project-name
## Quick Start
const thing = require('project-name');
const result = thing.doSomething('input');
console.log(result);
## API Reference
### doSomething(input)
- input (string): Description
- Returns: Description
## Contributing
[Steps to contribute]
## License
MIT
I built a README generator at zovo.one/free-tools/readme-generator that walks you through each section with prompts and produces a well-structured markdown file. It covers standard sections, badges, table of contents, and common patterns for different project types (libraries, CLIs, APIs, applications).
I'm Michael Lip. I build free developer tools at zovo.one. 500+ tools, all private, all free.
Top comments (0)