I reviewed 50+ GitHub repos this month while working on client projects.
Most developers had the same 5 problems in their README. The sad part? Their code was actually good — but the README made it look amateur.
Here's what I found — and exactly how I fixed them in my own projects.
1. No clear "What does this do?" line
Most READMEs start like this:
"This project uses Node.js, Express, MongoDB and React..."
Nobody cares about your tech stack in the first line. They want to know what problem your project solves.
Fix it — write one sentence like this:
"Invora is a GST invoice generator for Indian freelancers to create, manage, and share professional invoices in seconds."
That's it. One line. What it does, who it's for, what problem it solves.
2. Missing badges
Badges are not just decoration. They tell a developer in 3 seconds:
- Is this project active?
- What tech does it use?
- Is there a license?
Without badges, your repo looks abandoned — even if you pushed code yesterday.
Fix it — add these at the top of your README:
Go to shields.io and generate badges for your exact stack. Takes 5 minutes.
3. No installation steps
This is the most common mistake I see.
Developer spends 3 months building a project. Then writes:
"Clone the repo and run it."
Run it how? What environment variables? Which Node version? Is there a .env.example?
I've seen people close tabs and move on just because they couldn't figure out how to run a project locally.
Fix it — write this exact format:
## Getting Started
### Prerequisites
- Node.js v18+
- MongoDB Atlas account
### Installation
1. Clone the repository
bash
git clone https://github.com/yourusername/your-project.git
cd your-project
2. Install dependencies
bash
npm install
3. Set up environment variables
bash
cp .env.example .env
Then fill in your values in `.env`
4. Run the development server
bash
npm run dev
Copy this template. Fill in your project's details. Done.
4. No screenshots or demo
Text tells. Screenshots sell.
If your project has a UI — a dashboard, a form, an invoice — show it. One good screenshot does more than 200 words of description.
In my Invora project (GST Invoice Generator), I added a single screenshot of the invoice preview screen. That one image instantly communicates what the whole project does.
Fix it:
- Take a clean screenshot of your best UI screen
- Add it right after your project description:
## Preview
No UI? Record a 30-second GIF using Loom or Kap and embed that.
5. No "Why I built this" section
This is the most underrated section in any README.
Recruiters and clients don't just want to see what you built. They want to understand how you think.
A short "Why I built this" section shows:
- You solve real problems
- You have product thinking
- You're not just copying tutorials
Fix it — add 3-4 lines like this:
## Why I Built This
Most Indian freelancers generate invoices manually in Word or Excel.
It's slow, error-prone, and looks unprofessional.
I built Invora to solve this — a clean, fast GST invoice generator
built specifically for the Indian freelance market.
That's it. Personal, specific, real.
Final Thoughts
Your code might be great. But if your README doesn't communicate that clearly — recruiters skip it, clients don't trust it, and other developers can't use it.
A good README takes 1-2 hours. It pays back every time someone lands on your repo.
I write professional GitHub READMEs for developers.
If you want a clean, well-structured README for your project — with badges, installation steps, screenshots section, and API docs — check out my Fiverr gig:
I'm a backend developer myself (Node.js, Express, MongoDB, AWS) — so I actually read your code and write a README that accurately reflects what you built. Not generic filler.
Did I miss anything? Drop your GitHub repo link in the comments — I'll give you one quick tip for free. 👇
Top comments (1)
Drop your GitHub repo link below — I'll give you one quick README tip for free 👇