MarkdownPaper Open reader

Guide

How to write a good README

A good README answers four questions in order: what is this, why would I use it, how do I install it, and how do I use it. Put the answers near the top, keep each one short, and show a working example instead of describing one.

Here is a free template with those sections already in place. Download it, replace the text, and delete what you do not need.

Download README-template.md Open it in the reader

4 min read7 sectionsUpdated 1 Oct 2026

On this page

A complete example

This is a short but complete README for a made up tool. Each part is explained below.

You write

# csv-tidy

Cleans messy CSV files: trims spaces, fixes line endings and removes empty
rows.

## Why

Exports from spreadsheets and old systems are rarely clean. csv-tidy fixes the
common problems in one command, so the file opens the same everywhere.

## Install

```sh
npm install -g csv-tidy
```

## Usage

```sh
csv-tidy input.csv > clean.csv
```

| Option     | What it does                  |
| ---------- | ----------------------------- |
| `-k`       | Keeps empty rows              |
| `-q`       | Prints nothing but the result |

## License

MIT

You see

csv-tidy

Cleans messy CSV files: trims spaces, fixes line endings and removes empty rows.

Why

Exports from spreadsheets and old systems are rarely clean. csv-tidy fixes the common problems in one command, so the file opens the same everywhere.

Install

npm install -g csv-tidy

Usage

csv-tidy input.csv > clean.csv
OptionWhat it does
-kKeeps empty rows
-qPrints nothing but the result

License

MIT

Section by section

The name and one line

Start with the project name as the title, then one sentence that says what it does. Not what it is built with, and not how it came to be: what it does for the person reading. If someone reads only this line, they should know whether to keep going.

You write

# csv-tidy

Cleans messy CSV files: trims spaces, fixes line endings and removes empty
rows.

You see

csv-tidy

Cleans messy CSV files: trims spaces, fixes line endings and removes empty rows.

Why

Two or three sentences on the problem. This is where you convince someone the project is worth their time. Skip it for tiny projects where the one line says it all.

Install

The exact command, in a code block, so it can be copied. If something must be installed first, say which version.

You write

## Install

Needs Node.js 20 or later.

```sh
npm install -g csv-tidy
```

You see

Install

Needs Node.js 20 or later.

npm install -g csv-tidy

Usage

The smallest example that does something real. People copy this first, so it has to work as written. Add more examples below it if the tool does more than one thing, and use a table for options.

Contributing, support and license

Say where to report bugs and how to send changes. Name the license, and link to the license file. For an open source project, the license line is one of the first things companies check.

What to leave out

  • A long history of the project. Put it in a blog post or a changelog.
  • Every option and edge case. Link to full documentation instead.
  • Badges for everything. One or two, like the build status, are useful. A row of twenty is noise.
  • "Coming soon". Describe what works today.

Common mistakes

  • No install or usage example. The most common reason people leave.
  • Commands that do not work when copied. Test them in a fresh folder.
  • A wall of text. Use headings, short paragraphs and lists. Markdown makes this easy; see the Markdown cheat sheet.
  • Out of date steps. Update the README in the same change as the code.

Check how it reads

Before you publish, read the README as a visitor would: formatted, top to bottom, without the code open next to it. Open the file in the README viewer to see it as a page, or paste a GitHub link to read a published one.

Questions

How long should a README be?

As short as it can be while still answering what, why, install and usage. For a small tool that is one screen. For a large project, keep the README short and link to fuller documentation.

Should a README have a table of contents?

Only if it is long enough to need one, roughly more than five sections. GitHub adds an outline menu to any README with two or more headings anyway.

What is the best README template?

The one that matches what your readers need first. The template on this page covers the sections almost every project needs and nothing else, which makes it a good start for most projects.

Can I use HTML in a README?

A little. GitHub allows simple HTML like <details> for a section that opens on click, <br> for a line break, and an <img> with a width. It strips scripts and inline styles.

Next