How to Write a Great README for an Open Source Project

A README that’s vague, outdated, or just a code dump doesn’t feel harmless. It quietly kills adoption.

Users hit “install” and get stuck. Maintainers answer the same question for the fifth time. Contributors show up, can’t build it, and move on. You end up with more issues that say “docs?” than issues that say “bug.”

This is why README best practices matter. Not because it looks nice. Because the README is the first acceptance test for your project’s clarity.

The weak README pattern (and why it fails)

Here’s the typical failure mode:

• “It’s a library that does X” (but X is unclear)
• Installation steps that don’t match the repo today
• Usage examples that don’t run without extra setup
• Contribution instructions that assume tribal knowledge

It’s not that people can’t read. It’s that they can’t verify your project quickly.

And verification is what they need at 2 a.m. when something fails on their machine.

Before / after (small but real)

Before (weak)

# my-cool-tool

A tool for stuff.

How to install:
- run npm i
- configure

Usage:
see examples/

Contribute:
PR welcome.

After (strong)

# my-cool-tool

A CLI that helps you validate infrastructure configs against your policy rules.

## Project summary
Supports YAML configs, produces actionable diffs, and exits non-zero on violations.

## Installation
npm i -g my-cool-tool

# Quick check
my-cool-tool --version

## Usage
my-cool-tool validate ./config.yaml

# Output:
# - prints violations grouped by rule
# - writes a diff file when --diff is enabled

## Configuration
The tool reads:
- policy: via --policy ./policy.yaml
- optional environment overrides: MY_TOOL_LOG_LEVEL

## Contributing
1) Fork and clone
2) npm ci
3) npm test
4) npm run lint

If you add a new command, update the README usage section and add a smoke test.

Same project. Same repo. But the “after” README answers the questions that block real work:

• What does it do?
• How do I run it right now?
• What does “right now” require?
• How do I change it without breaking things?

README best practices: what each section is for

Your README isn’t a Wikipedia entry. It’s a route map. Different readers need different outcomes.

• Users want to install + run a happy path.
• Contributors want a working dev loop.
• Maintainers want fewer repeated questions.

So design your structure around those outcomes.

Project summary (the “why you should care” block)

Keep it short. One paragraph. Then—if it’s useful—add 2–4 bullet points.

People scan for:

• What problem does it solve?
• Who is it for?
• What makes it different (even if the difference is simple)?

Don’t hide the point under “Features.” If you have features, they should support the summary, not replace it.

Installation (the “can I run this on my machine?” block)

This is where most READMEs lie.

Write installation instructions that match how users actually install the package:

• Libraries: package manager commands and version info
• CLI tools: global vs local install (and why)
• Multi-repo projects: which repo a user should clone
• Required prerequisites: runtime versions, build tools, OS notes

If you have multiple install paths, name them explicitly. Example:

• “Install from npm for production use.”
• “Use the Docker image for CI or air-gapped environments.”

This is an edge case, but it’s common—and it’s where users waste hours.

Usage (the “show me the happy path” block)

Usage should include at least one runnable example.

For libraries, that means code that compiles/runs in a real project (even if it’s minimal). For CLI tools, that means a command that works without secret sauce.

If your CLI has multiple commands, don’t dump a wall of arguments. Give a short command list with what each command does:

• validate: check a config file
• report: generate HTML output
• rules: list available rules

That covers another edge case: “CLI tools with several commands.” People don’t want to read a flag reference first. They want the right first command.

Configuration (the “what knobs matter?” block)

Configuration is where environment variables and external services usually sneak in.

Be explicit about:

• Required config fields (and their defaults)
• Optional fields that change behavior
• Environment variables: name, meaning, and default behavior when missing
• External service dependencies: what you call, what credentials you need, and what happens when the service is unavailable

If your project depends on an external service, name it directly. For example:

“This tool calls the Acme Policy API. You need an API token. If the API is down, validation fails with a clear error and exit code 2.”

That prevents the “docs don’t mention this” loop.

Contributing / contributing guide (the “how do I help?” block)

This section exists for contributors. Not for users reading casually.

Link to a deeper contributing guide if you have one. But your README should still answer the minimum dev loop:

• How to get the code
• How to install dependencies
• How to run tests or at least a smoke test
• Any required formatting/linting

Include one sentence about how you judge contributions.

For example: “Bugs require tests. Features require an example and an update to the usage section.”

That single line cuts down on “I don’t know what you meant by documentation updates.”

Tailor the README to your audience (not to the tool you used)

There’s a temptation to write one README for everyone. Don’t.

Instead, pick a default reading path:

• Users start at Installation, then jump to Usage.
• Contributors start at Installation too, then immediately go to Contributing.

Now make it easy for those jumps to work.

Two simple tactics:

• Use a table of contents with anchor links (so scanning stays fast).
• Make the “happy path” examples early. Don’t bury them under advanced configuration.

And keep the document scannable:

• Headings that describe intent (“Configuration”, not “Details”)
• Examples that show input + output
• Minimal but sufficient detail (enough to run, not enough to memorize)

Keep it honest: edge cases you should name

Most projects don’t fail because the maintainers didn’t care. They fail because a README doesn’t cover the weird paths.

Three edge cases show up constantly:

Multiple install paths

If there’s more than one supported install method, name all of them. Users will choose the wrong one otherwise. Then they’ll blame you in an issue.

CLI tools with several commands

Document the commands as a quick map, not as a full reference. Put the reference in docs if you must, but your README should get people to a working first run.

External services and environment variables

If you require credentials, say so in Configuration. If behavior changes based on env vars, list the variables and defaults. If services can fail, explain the failure mode.

This is where users get stuck. And where “works on my machine” becomes “works on nobody’s machine.”

Use a README template… but make it your project’s brain

A README template helps you avoid blank-page drift. It won’t automatically produce clarity.

Pick a structure that matches your project type:

• Library: install → minimal example → configuration → dev setup
• CLI: install → quick command(s) → command map → configuration → contributing
• Tool that integrates external services: add a clear “requirements” note early

Also, don’t treat the README as a one-time write. Treat it like a living contract. When the behavior changes, the README must change too.

One quick way to keep it from rotting: connect the README to a place that you already update (release notes, docs site, or examples folder). The README should pull truth from the same source wherever possible.

Make the README do work (not just inform)

Here’s the practical trick I trust:

Use your README as the first acceptance test for a new contributor.

When someone new joins, don’t send them a setup wiki. Ask them to:

1. Follow Installation from a clean machine (or a fresh container).
2. Run the first Usage example.
3. Report where they got stuck.

If they can’t get through it, the problem isn’t their motivation. It’s your README.

And if you do this yourself once in a while, you catch gaps before users open issues. Run through Installation from scratch. Make sure examples match current behavior. Then update anything that diverged.

That’s README best practices in practice: clarity you can verify.