Blog · Documentation
How to document an open source project for the next maintainer
Documentation is the artefact that survives the handoff. The 6 documents every OSS project should have, plus the 2 that make a handoff possible.
Published July 13, 2026 · ~4 min read
The 6 standard docs
- README — the entry point
- CONTRIBUTING — how to contribute
- CODE_OF_CONDUCT — the social contract
- CHANGELOG — what changed
- LICENSE — the legal terms
- ARCHITECTURE — how the code is organized
The 2 docs that make a handoff possible
Beyond the 6 standards, two more make the handoff actually work:
NEXT_STEPS.md
A short document that says: "If you're a new maintainer, here's what to work on first. Top 3 issues by priority. Most-requested feature. The technical debt I'm aware of." This is the single most useful document you can write. Without it, the new maintainer has to dig through 50 issues to figure out where to start. With it, they ship a release in their first week.
MAINTAINERS.md
A short document that says: "Current maintainers are X, Y, Z. X is the release manager. Y owns the issue triage. Z owns the security disclosures. The chain of decision-making is ..." Without this, the new maintainer has to figure out who to ask for what — and risks stepping on someone's role.
The 80/20 of documentation
Most open source projects over-document the wrong things. The 80/20 of documentation:
- README with a good quickstart — 80% of users never read anything else
- CONTRIBUTING with a clear "how to set up the dev environment" — 80% of contributors bounce if this is missing
- NEXT_STEPS for the new maintainer — 80% of the handoff value comes from this single document
Everything else is nice-to-have. The error most projects make is to skip NEXT_STEPS and write a 2,000-line ARCHITECTURE document instead.
Frequently asked questions
What documents does every OSS project need?
README, CONTRIBUTING, CODE_OF_CONDUCT, CHANGELOG, LICENSE, ARCHITECTURE.
What's the most underdocumented part?
The 'next steps' section. Most projects have a roadmap buried in 50 issues.
How much documentation is too much?
Keep each doc focused. README < 500 lines. CONTRIBUTING < 200 lines. The 80/20 matters.
Related reading
Get rescued projects in your inbox
A short Monday-morning note on the projects abandoned last week and who adopted them. No spam, unsubscribe anytime.
Related reading on BreakPoint
The concepts, guides, and reports behind this post.