How to Write a Great README.md (With Examples)

Before anyone reads your code, they read your README. It is the single biggest factor in whether a stranger tries your project, stars it, or closes the tab in ten seconds. A great README explains what a project does, why it matters, and how to get started — fast. This guide walks through the sections every README needs, shows good versus mediocre examples, explains badges, and covers how to keep your README from going stale.

Why the README Is the Most Important File in Your Project

On GitHub, the README.md renders automatically below your file list — it is the first (and often only) thing a visitor reads. On npm, it becomes the entire package page. Recruiters skim it to judge your work. Contributors decide whether to open a PR based on it. And future-you, six months from now, will thank present-you for writing down how to actually run this thing.

A project with clean code but no README gets ignored. A project with average code but a clear README gets used, forked, and improved. Documentation is not an afterthought — it is part of the product.

The Essential Sections Every README Should Have

1. Title and tagline

One line that says what the project is, in plain language. Not marketing fluff — just clarity. "A lightweight CLI for converting cURL commands into fetch, axios, and Python code" tells you exactly what you're looking at.

2. Badges

A row of small status images right under the title — build status, npm version, license, downloads. Covered in detail below.

3. Description

Two or three sentences expanding on the tagline: what problem it solves, who it's for, and what makes it different from alternatives.

4. Installation

## Installation

npm install my-package

# or with yarn
yarn add my-package

Copy-pasteable commands, nothing else. If there are prerequisites (Node version, environment variables, a running database), list them right here.

5. Usage

## Usage

const { convert } = require('my-package');

const result = convert('curl -X POST https://api.example.com/users -d "name=Ravi"');
console.log(result.fetch);

A working code sample a reader can copy and run immediately, with the expected output shown alongside it. This is the section people scan first — put it early.

6. Features

A short bullet list of what the project can do. Skimmable, not a wall of text.

7. Contributing

How to set up a dev environment, run tests, and submit a pull request. Even one paragraph lowers the barrier for someone who wants to help.

8. License

One line naming the license (MIT, Apache 2.0, GPL) and a link to the LICENSE file. Without this, companies legally cannot use your code — many will not even check, they will just skip the project.

Good vs Mediocre: Section by Section

Description

Mediocre: "This is a tool for APIs."

Good: "A free browser-based tool that converts REST API endpoints into clean
Markdown documentation — no signup, no server, works entirely client-side."

Installation

Mediocre: "Clone the repo and install dependencies."

Good:
git clone https://github.com/you/project.git
cd project
npm install
npm run dev
# App runs at http://localhost:3000

The difference is specificity. "Good" examples give exact commands a reader can paste into a terminal with zero guessing. "Mediocre" examples force the reader to figure out the details themselves — and most will give up instead.

Badges Explained: What Build, Version, and License Badges Communicate

Badges are small SVG images generated by services like shields.io and embedded with Markdown image syntax:

![build](https://img.shields.io/github/actions/workflow/status/you/project/ci.yml)
![npm version](https://img.shields.io/npm/v/my-package)
![license](https://img.shields.io/badge/license-MIT-blue)
![downloads](https://img.shields.io/npm/dm/my-package)

• Build/CI badge — shows whether the latest commit passes tests. A green badge signals the project actually works right now.
• Version badge — the current published version on npm/PyPI, so users know if they are looking at something current or abandoned.
• License badge — instantly answers "can I use this in my company's product," without opening a LICENSE file.
• Downloads badge — a rough signal of adoption and trust, useful when a reader is comparing two similar packages.

None of these are required, but on npm and GitHub they act like a trust signal at a glance — readers form an opinion before reading a single word of your description.

Keeping Your README Maintained as the Project Evolves

• Update it in the same PR as the feature — if a flag or command changes, the README change belongs in that same commit, not a "docs later" TODO.
• Treat broken examples as bugs — if a copy-pasted usage snippet from the README no longer runs, that is a defect, not a documentation nitpick.
• Re-read it from a stranger's perspective every few months — assumptions that were obvious to you at version 0.1 often are not obvious anymore at version 2.0.
• Move deep details out of the README — advanced configuration, API references, and architecture notes belong in a `/docs` folder linked from the README, keeping the top-level file scannable.
• Delete stale sections — an outdated "Roadmap" or "Known Issues" section that hasn't been touched in a year does more harm than having none at all.

Frequently Asked Questions