How to Write a Great README.md (2026)
Your README is the first thing people see when they find your project. A good README turns visitors into users and contributors. A bad one — or worse, a missing one — makes people leave immediately. In the open source world, the README is your project's resume, documentation, and marketing page rolled into one.
- Write effective README files for your projects.
- Covers essential readme sections.
- Covers writing a good description.
- Covers installation and usage.
- Covers badges and license.
Essential README Sections
Every README needs at minimum: project name, one-line description, installation instructions, and basic usage. These four elements let someone understand what your project does and start using it in under two minutes.
Beyond the minimum: a table of contents (for long READMEs), configuration options, API documentation, contributing guidelines, and license. The more mature your project, the more sections it needs.
Order matters. Put the most important information first. Name, description, and quick start should be visible without scrolling. Configuration details, API docs, and contributing guidelines can live further down.
Writing a Good Description
Lead with what the project does, not how it works. "A CLI tool that converts Markdown to PDF with syntax highlighting" tells users immediately whether this project solves their problem.
-webkit-backdrop-filter alongside backdrop-filter for Safari support. Without the prefix, the effect is invisible to roughly 25% of mobile users.Include a key differentiator. What makes this project better than alternatives? Faster? Simpler? More configurable? "Zero-dependency Markdown to PDF converter with GitHub-flavored syntax highlighting" adds two differentiators.
Avoid jargon in the description. A new user should understand the value proposition without knowing your tech stack. Save technical details for the installation and architecture sections.
Installation and Usage
Installation instructions should be copy-paste ready. Show the exact command: npm install my-tool or pip install my-tool. Test your installation instructions on a clean machine — missing dependencies are the number one README complaint.
backdrop-filter inside a position: fixed element can cause severe scroll performance issues. Test thoroughly on real iOS devices.Show a basic usage example immediately after installation. The fastest path from install to working output. If it takes more than three commands, simplify your API or add a getting started guide.
Include expected output. When someone runs your example, what should they see? Showing the expected result helps users verify their setup is working correctly.
Badges and License
Badges communicate project health at a glance: build status, test coverage, latest version, license type, and download count. Place them at the very top of the README, right after the project name.
shields.io generates badges for virtually any metric. The format is straightforward:  creates a blue MIT license badge.
Every open source project needs a license. Without one, your code is under exclusive copyright — no one can legally use it. MIT is the most permissive and popular choice. Apache 2.0 adds patent protection. GPL requires derivative works to also be open source.