I'm learning to code. Along the way I've noticed something: the part of a project I understand fastest is usually the README. When a README is unclear, I often give up before I ever open the code.
Writing is the part I'm comfortable with, so here are the habits I keep coming back to when I read (and try to write) READMEs.
Start with one sentence that says what it is
The first line should answer "what is this, and who is it for?" Most visitors decide within seconds whether to keep reading. A sentence like "A command-line tool that renames photos by the date they were taken" does more work than three paragraphs of background.
Show it working before you explain it
People want to see the result first. A short example near the top beats a long feature list:
## Quick start
npm install my-renamer-tool
my-renamer-tool ./holiday-pics
Before: IMG_4021.jpg
After: 2026-08-14_10-32-05.jpg
Once readers can see what happens, the details that follow make sense.
Write install steps as if the reader knows nothing
It's easy to skip steps that feel obvious to you. When I follow installation guides as a beginner, the missing piece is almost always something the author did without thinking: a required version, an environment variable, a folder you must be in. Numbered steps, one action each, are hard to get wrong.
Use headings as a map
Many readers scan instead of reading top to bottom. A predictable set of headings helps them jump to what they need:
- What it is
- Quick start
- Installation
- Usage
- Configuration
- Contributing
- License
Not every project needs all of them, but sticking to familiar names means people don't have to guess.
Cut the words that don't help
Editing habits carry over well from ordinary writing:
- Replace "In order to" with "To".
- Delete "simply" and "just". If the step were simple, the reader wouldn't be in the docs.
- Keep paragraphs short. Three or four lines is plenty on a screen.
Keep it true
A README that describes last year's version is worse than a short one. If a command changes, the README should change in the same commit. That's a coding habit I'm still building, but it's the one that seems to matter most.
What I'm still figuring out
I haven't settled how much detail belongs in the README and how much should move to separate docs. My current rule of thumb: the README gets someone from "what is this?" to "it works on my machine". Anything beyond that gets its own page.
If you have a README you think does this really well, I'd love to see it in the comments. Good examples are the best way I've found to learn.
Top comments (0)