What sections should every OSS README have?

Seven: (1) one-sentence project description; (2) why this exists; (3) quickstart / install; (4) usage example; (5) contributing link; (6) license; (7) maintainer status (who maintains this, are they looking for help, how to contact them). The 7th is the one most projects miss and is the one that makes a handoff possible.

How long should a README be?

Long enough to answer the four questions a new contributor has: what is this, how do I install it, how do I use it, how do I contribute. For a small library, that's 200-400 lines. For a larger framework, 500-1000 lines is fine. The mistake is going too short (under 100 lines) or padding with badges and 'we use X' sections.

What about the README that gets you contributions?

Three things: (1) a 'good first issue' link or label in the README, (2) a clear contributing guide linked from the README, (3) a 'how to set up the dev environment' section. Most first-time contributors bounce because they can't get the project to build locally — a 5-line 'how to develop' section cuts your contributor-bounce rate in half.

Blog · README

How to write a README that survives a maintainer handoff

A README is the first thing a new maintainer reads. It is also, in 80% of cases, the only thing they read before deciding whether to take on your project. This guide covers the 7 sections every OSS README should have — plus the 3 sections that make a handoff possible.

Published July 13, 2026 · ~5 min read

The 7 sections

One-sentence project description
Why this exists (the problem you solve)
Quickstart / install
Usage example
Contributing link
License
Maintainer status (who maintains this, are they looking for help)

The 7th section is the one most projects miss — and the one that makes a handoff possible.

Each section, in detail

1. One-sentence project description

The first line. Should answer "what is this?" in plain English. No marketing speak, no clever metaphors. "A static site generator for blogs" is better than "The next generation of content creation tooling."

2. Why this exists

The problem you solve. Two or three sentences. A new contributor who understands the problem is 10× more useful than one who just understands the code.

3. Quickstart / install

The fastest path from npm install (or equivalent) to "hello world." Should be copy-pasteable. The best READMEs have a 5-line quickstart that ends with output the reader can see.

4. Usage example

A more substantive example that shows the project's main use case. Often a 20-30 line code block with comments.

5. Contributing link

Link to CONTRIBUTING.md. The contributing guide itself should cover: how to set up the dev environment, how to run tests, how to submit a PR, the project's code style.

6. License

One line: "This project is licensed under the MIT License — see the LICENSE file for details." Plus a LICENSE file in the repo root.

7. Maintainer status — the one that matters

This is the section that most projects miss. A short paragraph saying: "This project is maintained by @your-handle. I'm actively shipping / I'm looking for a co-maintainer / I'm stepping back and looking for a successor — see [link to drop on BreakPoint / adopt-me issue / Adoptoposs entry]." The maintainer status is the signal that closes the loop. Without it, the new maintainer has to guess.

The 3 sections that make a handoff possible

Beyond the 7 essential sections, three more are what make a handoff actually work:

"Next steps" section. What would the next maintainer work on first? List the top 3 issues, the most-requested features, the technical debt. This is the document that turns "I might take this over" into "I can take this over."
"How to develop" section. How to set up the dev environment, how to run tests, how to deploy a release. The 5-line version cuts contributor-bounce rate in half.
"Architecture" section. One paragraph or one diagram: "this project has 3 modules: A, B, C. A handles X, B handles Y, C handles Z. The dependency graph is ...". A new maintainer who understands the architecture is a maintainer who can ship in week 1.