A README template that people actually read

The README is the most-read file in any repository and the least-loved to write. Someone lands on your project cold. In a few seconds they decide whether it does what they need and whether it is worth their time to try. A good README answers both questions before they scroll, then gets out of the way. This is a template that does that, followed by the reasoning, because copying a skeleton is easy and knowing why each part earns its place is what keeps yours from bloating.

The template

Copy this, delete what does not apply, and fill the rest. The order is deliberate and the next section explains it:

# Project Name

One sentence that says what this is and who it is for.

<!-- badges: build status, version, license. Optional. -->

## Quick start

    npm install project-name

    import { thing } from "project-name";
    thing.doTheObviousThing();

## Usage

A slightly fuller example than the quick start, showing the
most common real task someone would use this for.

    const result = thing.configure({ mode: "fast" }).run();

## Configuration

| Option   | Type    | Default | Description                 |
| -------- | ------- | ------- | --------------------------- |
| mode     | string  | "safe"  | "safe" or "fast".           |
| timeout  | number  | 5000    | Milliseconds before giving up. |
| retries  | number  | 3       | Attempts before failing.    |

## Contributing

How to run the tests and open a pull request. Link to a
CONTRIBUTING.md if the details are long.

    npm install
    npm test

## License

MIT. See LICENSE.

Why the sections are in this order

Every choice here is about getting a reader from “what is this” to “it works on my machine” with the fewest questions. Section by section:

Name and one-liner: the first screen decides everything

The single sentence under the title is the most valuable line in the file. A reader skims it and either keeps going or closes the tab. Say what the thing is and who it is for, in concrete terms. “A caching layer for HTTP responses in Node” tells a reader in one breath whether they are in the right place. A paragraph of vision does not.

Badges: optional, and easy to overdo

A build-status badge and a version badge give a quick signal that the project is alive and tells a reader which release the docs describe. That is the useful core. A row of fifteen badges is noise that pushes the actual content below the fold, so keep it to the two or three that a visitor would genuinely act on.

Quick start before philosophy

This is the rule most READMEs break. People arrive wanting to run something in the next minute. Put the install command and the smallest working example above everything else, so a reader can copy, paste, and see it work inside a minute. The motivation, the architecture, the comparison table, all of it can wait until after the reader has decided the thing is worth their attention, which the quick start is what earns.

Usage: the common real task

The quick start proves the thing runs. The usage section shows it doing the job someone actually installed it for, one step past “hello world”. Pick the single most common real use and show it end to end. One good, realistic example teaches more than ten trivial ones, and it doubles as a spec for what you consider the happy path.

Configuration as a table

Options belong in a table. A reader scanning for “can I change the timeout” finds it in a column far faster than in a paragraph. Columns for the option name, type, default and a one-line description cover almost every case, and the defaults column quietly documents the behaviour you get if you configure nothing.

Contributing and license: short and present

Most projects need only two lines of contributing guidance: how to run the tests and how to open a pull request. If the details grow, move them to a CONTRIBUTING.md and link it, so they do not crowd the README. The license line is small but not optional. Code with no stated license is, legally, code no one is allowed to use, so name it and link the full text.

Keep the claims testable

A README rots faster than any other file because the code moves and the prose does not. The defence is to write claims that can be checked and to check them:

• Every code block should run against the current version. Stale examples are the fastest way to lose a new user.
• The configuration table should match the actual defaults in the code, checked against the source rather than memory.
• Version-specific claims should say which version, the same discipline semantic versioning asks of your release numbers.

If your commits follow conventional commits, a generated changelog already tracks what changed between versions, which takes some of the documentation burden off the README and onto a file that updates itself.

When to split into a docs site

A README has a natural ceiling. It is one scrollable page, and past a certain size it stops being scannable. The signal to split is not a word count so much as a feeling: when readers have to use the browser’s find to locate a section, when a table of contents becomes necessary, or when you have three tutorials fighting for space, the content has outgrown the file.

At that point, move the depth to a documentation site and keep the README as a landing page: the one-liner, the quick start, and a prominent link to the full docs. The README’s job never changes. It gets a reader oriented and running fast. Once the reader is committed, a dedicated site serves the reference material better than an ever-growing single file ever could.

A minimal version for a small library

A focused library that does one thing does not need the full skeleton. Everything above the fold, nothing below it. This is often all a small package should carry:

# slugify-fast

Turn any string into a URL-safe slug. Zero dependencies.

    npm install slugify-fast

    import { slugify } from "slugify-fast";

    slugify("Hello, World!");  // "hello-world"

## Options

    slugify("Crème Brûlée", { locale: "fr" });  // "creme-brulee"

MIT licensed.

That is a complete, honest README. It names the thing, proves it works, shows the one option people reach for, and states the license, all on a single screen. When the library grows, the sections from the full template are waiting. Until then, do not add structure the project has not earned. A README that is finished on one screen beats one padded to look substantial. When you are drafting one, a live Markdown editor shows the render as you type, and a word counter is a quick gut check that you have not let the intro sprawl. Keep the whole thing next to your PR template as part of the boilerplate a healthy repo ships with.