A README is the front door of your project. It runs before the code, before the tests, and before anyone decides whether to clone. In 2026, with AI-assisted code generation making repositories cheaper to spin up, the bottleneck in adoption has shifted entirely to documentation quality. Here is how to write one that works.
What changed in 2026
- AI copilots read READMEs to scaffold usage. Tools like GitHub Copilot, Cursor, and Claude pull the README as context when helping contributors onboard. A structured README makes AI assistance better.
README.md is now auto-rendered in more places — npm, PyPI, crates.io, and GitHub all surface it prominently. One file, many audiences.- Spec-based generation tools (
readme-ai, autodoc) can draft a scaffold from code, but the output still needs human editing for accuracy and tone.
- Monorepo workspaces have normalized per-package READMEs; the root README is now a navigation layer, not a docs dump.
Anatomy of a good README
A well-structured README in 2026 follows this order:
| Section |
Purpose |
| Title + one-liner |
What is this? |
| Badges (1 row max) |
CI status, version, license |
| Quickstart |
Working copy-paste install + first run |
| Usage / examples |
The two most common tasks, with code |
| Configuration |
Key options, not every flag |
| Contributing |
How to open a PR |
| License |
One line |
Sections below "Usage" are needed only if the project warrants them. Do not add sections to look thorough.
The one-liner
The first sentence after the title must answer: "What does this do and for whom?" Bad: "A utility library." Good: "A zero-dependency TypeScript library that validates ISO 8601 date strings at parse time."
Quickstart section
This is the highest-value section. It must work on a fresh machine with no assumed context. Test it.
# Install
npm install @myorg/dateval
# Basic usage
node -e "const {validate} = require('@myorg/dateval'); console.log(validate('2026-06-01'))"
If setup requires environment variables, show the .env.example content inline. Do not say "set the required env vars" and leave it there.
Usage examples
Show the two or three things 80 % of users will actually do. Use runnable code blocks with a language tag. Prefer real outputs in comments:
import { validate, parse } from '@myorg/dateval';
validate('2026-06-01'); // true
validate('not-a-date'); // false
const d = parse('2026-06-01');
d.year; // 2026
How to pick what to include
- Would a new contributor need this on day one? Include it.
- Is it covered better in linked docs? Link, do not duplicate.
- Is it an edge case most users never hit? Put it in a wiki page or
/docs.
- Does it change every release? Pull it from source (changelog link) rather than duplicating it in the README.
Badges
One row. CI (green/red), latest version, license. That is it. Avoid "made with love" and language-percentage badges — they add no information.
[](https://www.npmjs.com/package/@myorg/dateval)
Tooling in 2026
markdownlint — catches broken headings, inconsistent lists, bare URLs.markdown-link-check — run in CI to catch dead links before they rot.readme-ai — drafts a scaffold from repo analysis; useful starting point, not final copy.- GitHub Actions — add a
docs job that runs lint + link-check on every PR touching README.md.
# .github/workflows/docs.yml
on:
pull_request:
paths: ['README.md', 'docs/**']
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx markdownlint README.md
- run: npx markdown-link-check README.md
Common mistakes
Outdated quickstart. The install command changed, nobody updated the README. Add markdown-link-check and a manual review step to your release checklist.
Configuration dumping. Pasting every CLI flag and every config key makes the README longer than the source. Link to a generated API reference instead.
No contributing section. Even "open a PR against main; CI must pass" is better than nothing. Contributors need a signal that PRs are welcome.
Assuming OS. "Run make build" breaks on Windows. Show the platform-agnostic path (npm run build) or explicitly note OS requirements.
What to skip
- Detailed changelogs inline. Keep a separate
CHANGELOG.md and link to it.
- Architecture diagrams for small libraries. A prose paragraph is faster to maintain and usually clearer.
- Code of conduct in the README. Link to
CODE_OF_CONDUCT.md in one line.
FAQ
How long should a README be?
Long enough to answer "what is this" and "how do I start." For most libraries, 100–200 lines. For frameworks or CLIs with many commands, longer is justified — but split into subsections.
Should I use a README generator?
Use one to generate a first draft, then edit aggressively. Generator output tends to be verbose and generic.
What about monorepos?
The root README explains the repo structure and how to run the workspace. Each package gets its own focused README covering only that package.
Do I need a logo?
Only if your project has visual branding. A logo adds load time and maintenance; skip it for internal tools and libraries.
Where to go next