How to Write a Good GitHub README (With Real Examples)

Your README is the single most important file in your repository, and it is also the one most teams treat as an afterthought. It is the first thing a potential user, contributor, or hiring manager sees. A good README answers, in under thirty seconds, three questions: what is this, why should I care, and how do I use it. A bad README leaves all three unanswered and quietly costs you users you never knew you had.

This guide walks through how to write a README that developers actually read, with concrete structure, real examples, and the templates that work for different kinds of projects.

Why your README matters more than you think

A README is a conversion surface. When someone lands on your repository from a search result, a social link, or a package registry, the README decides whether they stay or leave. People do not read repositories top to bottom — they scan the README, and if it does not immediately communicate value, they close the tab.

For open-source projects, the README is your marketing page, your onboarding doc, and your support FAQ rolled into one. For internal projects, it is the difference between a new teammate being productive in an hour versus a day. The cost of a weak README is invisible but real: abandoned evaluations, repeated questions in Slack, and contributors who give up before their first pull request.

If you want to measure how your current README stacks up, our free repository analyzer gives you an instant health score based on documentation signals.

The anatomy of a perfect README

A strong README follows a predictable shape because predictability is what makes it scannable. The reader knows where to look for installation, where to look for usage, and where to look for license. Fighting that convention only slows people down.

The canonical order is: a one-line description, a longer paragraph of context, a visual (screenshot, GIF, or diagram), installation, usage, configuration, contributing, and license. You do not need all of these for every project, but you should consciously decide which to include rather than omitting them by accident.

Essential sections every README needs

Project title and one-line description. The first line should tell a stranger exactly what the project does. "A TypeScript-first ORM for PostgreSQL" beats "The best database tool ever" every time. Be specific; specificity signals competence.

A short context paragraph. Two to four sentences explaining the problem the project solves and who it is for. This is where you earn the reader's attention.

Installation. Give the exact command. Do not assume the reader knows your package manager conventions. If there are prerequisites, list them with versions.

Usage. Show a minimal, copy-pasteable example that actually runs. The single biggest README failure is a usage section that references functions or config that no longer exist. Real, working examples build trust.

Configuration and API reference. If your project takes options, document them in a table with the option name, type, default, and description. Tables are scannable; prose is not.

Contributing. Even a single line — "PRs welcome, run npm test before submitting" — lowers the barrier to contribution dramatically.

License. State it explicitly. Ambiguous licensing scares off serious users.

README templates for different project types

Different projects need different emphasis. A library should lead with installation and a usage example, because the reader is evaluating whether to depend on it. A CLI tool should lead with a GIF of it running, because the value is visual and immediate. An application or service should lead with setup and environment configuration, because the reader is trying to run it locally. An open-source framework should invest heavily in the contributing section and link out to deeper documentation.

The fastest way to get a correct, project-appropriate starting point is to generate one from your actual code. Our free README generator reads your repository — your package manifest, entry points, and file structure — and produces a complete, accurate README in seconds. It is a far better starting point than a blank file or a generic template, because it describes your code as it actually exists.

Common README mistakes to avoid

The most common mistake is the stale README: instructions that worked six months ago but now reference a removed flag or an old install command. A README that lies is worse than no README, because it actively wastes the reader's time and erodes trust.

The second mistake is assuming context. Authors know their own project so well that they skip the obvious. The reader does not know what pnpm run seed does or why they need a .env file. Spell it out.

The third is wall-of-text syndrome — paragraphs where there should be tables, lists, and code blocks. Developers scan. Give them visual structure.

The fourth is burying the value. If your project's killer feature is on line 200, most readers will never see it. Lead with what makes the project worth using.

How to keep your README up to date automatically

Here is the uncomfortable truth: even a perfect README decays. Code changes, flags get renamed, dependencies get swapped, and nobody remembers to update the README because updating documentation is never the most urgent task on a sprint board.

The only durable solution is to remove the human from the maintenance loop. Instead of relying on someone to remember, you can wire documentation updates to the one event that always happens when code changes — a git push. This is the model Pushpen uses: every push triggers an AI review of the diff, and if your README is now inaccurate, a pull request opens with the fix. You review and merge. The README stays current without anyone having to think about it. You can read more about this approach in our guide on keeping your README updated automatically, or see why documentation goes outdated in the first place.

Real examples from popular open source repos

The best-documented projects share a pattern. They open with a crisp description, show the value immediately, and make the first run effortless. Projects like well-maintained ORMs, popular CLIs, and widely-used frameworks all front-load a working example and keep installation to a single command. Notice what they do not do: they do not bury the reader in philosophy before showing code, and they do not pad the README with badges that communicate nothing.

Study three or four READMEs from projects you admire in your own ecosystem. You will see the same skeleton every time. Borrow it. Conventions exist because they reduce cognitive load, and a README is the wrong place to be original about structure.

For more on this, our deep dive into GitHub README best practices covers formatting, badges, and audience-specific structure in detail. And if you want to start from a clean, accurate baseline today, the Pushpen homepage explains how automated documentation fits into your existing GitHub workflow.

Frequently Asked Questions

How long should a GitHub README be?

Long enough to answer what the project is, how to install it, and how to use it — and no longer. For most libraries that is 100 to 300 lines. If your README grows past that, move deep reference material into a docs/ folder and link to it, keeping the README itself scannable.

What is the most important section of a README?

The first three lines. The title and one-line description determine whether a reader continues. After that, a working usage example matters most, because it proves the project does what it claims and shows the reader how to get value quickly.

Should I write my README before or after the code?

A short README written early forces you to articulate what you are building and for whom, which often improves the design. Then keep it in sync as the code evolves. The failure mode is writing it once and never touching it again.

How do I keep my README from going out of date?

Tie updates to your workflow instead of memory. Automating README updates on every push — the approach behind Pushpen — means the README is corrected as part of shipping code rather than as a separate chore people forget. You can also periodically run a README audit to catch drift.

Can I generate a README automatically?

Yes. A tool like the free README generator reads your repository and produces a complete first draft from your real code, including installation and usage sections. It is the fastest way to go from an empty file to a solid, accurate baseline.