How to Write a README.md People Will Actually Read
Quick answer
A README people actually read answers five questions fast: what the project does, why it's useful, how to get started, where to get help, and who maintains it — the same five GitHub itself recommends. Keep it skimmable — short paragraphs, descriptive headings, a code block instead of a paragraph of instructions. Below: how to structure one, the mistakes that make people bounce off a README, and how to write and revise yours in Carets.
Step-by-step
1. Start with the name and a one-line description
Open with the project's name and one plain sentence describing what it does. Not "a great tool for managing tasks" — the actual thing: what input it takes, what it produces, who it's for. A stranger skimming your repository for ten seconds should know whether this is relevant to them.
If the name doesn't make the purpose obvious, that one-line description is doing all the work. Write it last, after you've drafted the rest of the README, so it reflects what the project turned out to be rather than what you planned when you started.
2. Answer what it does and why it's useful
This is the part most READMEs skip. Say what problem the project solves and why someone would reach for it over the alternative. GitHub's own guidance puts "why the project is useful" right next to "what it does" — they're not the same sentence, and both matter.
3. Add install and usage, with real code
Show, don't tell. A fenced code block with the actual install command, followed by a minimal usage example and the output someone should expect to see, does more work than three paragraphs of prose. Shipping badges — build status, license, current version? Put them right under the title, where a reader sees them before anything else.
4. Reach for a table when a list gets crowded
Once you're past three or four configuration options, a bulleted list stops being scannable. Switch to a Markdown table instead — one row per option, one column for the default, one for what it does. Easier to scan, and easier to keep accurate as options change.
5. Add support, license, and status
Close with where people should file issues or ask questions, what license applies, and whether the project is actively maintained. Make a README frames this well: a README exists to answer the questions your audience will have anyway, so answer them once, in writing, instead of one Slack message at a time. Its advice about length is blunt, too — too long beats too short, and heavier reference material belongs in a linked doc, not wedged into the root file.
The all-caps filename is a small piece of software history worth knowing. It dates to 1970s Unix conventions, chosen specifically so the name would sort near the top of an ASCII-ordered file listing, where most filenames were lowercase. The convention outlived the reason for it, and every GitHub repository still uses it.
Common problems and fixes
Written last, rushed, incomplete. A README treated as a docs afterthought reads like one. Put it in the project plan, not just the docs plan, and write a rough version before you're deep into the code — you'll often catch a confusing API or missing step while the project is still fresh in your head.
Over-specified and unskimmable. Piling in every configuration flag and edge case makes a README "overwhelming or unwieldy," as one guide to engaging READMEs puts it. Finding the right depth takes some trial and error. Keep the root file to what a new user needs in the first five minutes; link out for the rest.
Absolute links that break on a fork. Point to docs/CONTRIBUTING.md, not a hardcoded URL to your default branch — GitHub resolves relative links per branch automatically, so they keep working after a fork or a rename. Same logic for a pull request template: keep the paths relative and it survives repo moves.
README that nobody sees. GitHub only auto-surfaces a README from three places — the .github folder, the repository root, or the docs directory, checked in that order. Put it anywhere else and it won't render on the repo's front page at all.
Missing dependencies or prerequisites. Assuming the reader has the same toolchain, runtime version, or system package you happen to have installed is a common way to lose someone at step one. List what has to already be on the machine before your install command works, even if it feels obvious to you.
Doing this with Carets
Writing and revising a README is a Markdown-editing task with a tight feedback loop: you write a heading, add a code fence, and want to see how it'll actually render before you commit it. Carets is built for exactly that — Markdown, plain text, and code in one editor, with syntax highlighting for the code blocks and config snippets a good README leans on. Got more than one doc for this project — a README, a CONTRIBUTING guide, a CHANGELOG? Carets keeps them organized into files, projects, and tags instead of scattered across app windows.
Get Carets for iPhone, iPad, and Mac on the App Store.
Frequently Asked Questions
What's the minimum a README needs to have?
A title and one-line description, what the project does and why it's useful, install and usage steps, and a license. Badges, a roadmap, and a contributing guide are additive — useful, but not the baseline.
Where does GitHub look for my README?
GitHub checks the .github folder, the repository root, and the docs directory, in that order, and renders whichever it finds first on the repository's front page.
How long should a README be?
Long enough to answer what, why, and how without skipping steps — short enough to skim in under two minutes. Push deep detail, like a full architecture writeup or API reference, into a linked docs site instead of stuffing it into the README itself.
Should I write the README before or after the code?
Before, or alongside it, if the project is going to be shared or public. Drafting the README first forces you to describe the project's purpose and usage in plain terms, which often surfaces gaps before you've written a line of code.