Your code is great. Your README is costing you stars.
I maintain 40+ open source projects on GitHub. After watching which ones get traction and which ones die in silence, the pattern is clear: the README makes or breaks it. Not the code quality, not the test coverage, not the CI badges. The README.
Here are 8 mistakes I see constantly, and what to do instead.
1. Leading with a description instead of a hook
What people do:
MyLib is a utility library for JavaScript.
Nobody cares. That tells me nothing about why I should pick this over the 500 other JS utility libraries.
What works:
Parse, validate, and transform dates in 400 bytes. No Moment, no Luxon, no dependencies.
Lead with the value. What pain does it kill? How small or fast is it? Give me a reason to keep reading in the first line.
2. No visual, no click
People scroll past text. They stop for images.
If your project has any kind of UI, a demo GIF is mandatory. For CLI tools, use asciinema or VHS. For web apps, record a short browser demo. For libraries, show code + output side by side.
Put the visual right after your hook, before the feature list. That's the best spot on the page.
3. Badge spam
I've seen READMEs with 12 badges. "Made with love", "code style: prettier", "contributions welcome", three different CI statuses.
Badges should signal project health at a glance. Stick to 3-5:
- npm version - proves it's published
- CI status - tests pass
- TypeScript - type safety signal
- License - MIT/Apache so people know they can use it
- Bundle size - only if size is a selling point
Every badge beyond that is noise.
4. Making installation take more than 30 seconds
From landing on your README to running code should take under 30 seconds.
npm install your-package
import { thing } from 'your-package';
const result = thing({ option: true });
Done. No "first make sure you have Node 18+" preamble. No "clone the repo and build from source." The fastest path from zero to working code.
5. Writing for readers instead of scanners
Developers don't read READMEs. They scan them. Long paragraphs get skipped entirely.
What works:
- Bold the key terms in the first sentence of each section
- Use tables for API options instead of nested lists
- Keep paragraphs under 3 sentences
- Use
code formattingfor anything technical - GitHub Alerts (
> [!TIP],> [!WARNING]) for callouts
If someone skimming for 10 seconds can figure out what your project does and how to install it, you've won.
6. Ignoring SEO entirely
Your README is indexed by Google, GitHub search, and increasingly by LLMs. Structure matters.
- One H1 (project name), H2s for sections, H3s for subsections. Don't skip levels.
- Alt text on images that describes what they show, not just "screenshot"
- Mention the problem domain in the first paragraph. "React hook for form validation" beats "a utility for validating things"
- Add a FAQ section. Both LLMs and Google love Q&A format.
A well-structured README ranks better than a bare repo with just code.
7. The 500-line README
If your README needs a table of contents, most of it should be in /docs. The README is a landing page, not a manual.
Keep the main scroll path lean. Use <details> blocks for verbose content like full API references or advanced config.
8. Outdated examples
This one is silent killer. Your API changed 3 months ago but the README examples still show the old API. Someone copies the code, it breaks, they close the tab and never come back.
Pin your README examples to real tests when you can. At minimum, try running them after every major change.
The tool I built for this
After writing 40+ READMEs by hand, I got tired of juggling badge URLs, table alignment, and pushing to GitHub just to check rendering. So I built README Builder - a visual drag-and-drop editor.
You drag blocks (headings, badges, code, tables, images, alerts) into place, see exactly how GitHub will render them, and copy the markdown when you're done. Free, open source, no login.
If this post was useful, give it a try: ofershap.github.io/readme-builder
The full best practices guide is also built into the app: README Best Practices Guide
ofershap
/
readme-builder
Visual drag-and-drop README editor with live GitHub-flavored preview. SEO-optimized templates, 15+ block types, import/export markdown.
readme-builder
Stop writing markdown by hand. Drag blocks, get a README.
Visual editor that turns drag-and-drop blocks into GitHub-flavored markdown.
Live preview, templates, import from GitHub repos, export when you're done
Your README Shouldn't Take Longer Than Your Code
You just built something cool. Now you need a README, and suddenly you're juggling markdown syntax, badge URLs, table alignment, and GitHub-flavored quirks. You know the drill:
- Copy-paste badge URLs from shields.io, typo the repo name, debug for 10 minutes
- Manually align tables, forget a pipe character, the whole thing breaks
- Check how the markdown renders by pushing to GitHub and refreshing
README Builder gives you a visual canvas where you drag blocks (headings, badges, code, tables, images, alerts) into place and see exactly how GitHub will render them. When it looks right, copy the markdown or export the file. Done.
Features
15 block types
Headings, badges, code, tables, lists, images,
Top comments (0)