Write a README a stranger can follow

Most project READMEs fail the 30-second stranger test. A good README lets someone with zero context understand what your project does, why you built it, and how to run it, without asking you a single question. It is often the first and only thing a reviewer reads, so it decides whether they look any further.

The 30-second stranger test

Picture the reader: someone who has never heard of your project, clicked a link from your portfolio, and will give it about 30 seconds before moving on. They cannot ask you anything.

In that time they need answers to three questions, in this order:

• What is this? One or two plain sentences.
• Why does it exist? The problem it solves or what you were learning.
• How do I run or see it? A live link, or setup steps that actually work.

Everything else, such as the tech stack, design decisions, and future plans, comes after those answers. A README that opens with a list of badges or a history of how the idea came about makes the reader dig for the basics.

Lead with what it does and why

The first lines should describe the project from the user's point of view, not the code's. Compare:

• Weak: "A React app using hooks and the Fetch API."
• Strong: "A weather dashboard that shows the next 7 days for any city, built to practise working with a real public API."

The strong version says what it does, who it's for, and why you built it. The stack still matters, but it belongs in its own short section further down.

A good "why" is honest and specific. "I wanted to learn how to handle loading and error states with real network requests" tells a reviewer more about you than "I wanted to build something cool."

Exact steps to run it

Setup instructions are where most READMEs break. "Install and run it" assumes knowledge the reader doesn't have. Spell out prerequisites and exact commands:

# Requires Node.js 22 or newer
git clone https://github.com/your-name/weather-dashboard.git
cd weather-dashboard
npm install
cp .env.example .env   # then add your free API key
npm run dev

Then say what should happen: "Open http://localhost:5173 and search for a city."

If the project needs an API key, commit a .env.example file with placeholder values like WEATHER_API_KEY=your-key-here and link to where the key can be obtained. Never put a real key in the README or the example file.

Show it and be honest about it

A live demo link is the fastest way to pass the 30-second test, because the reader doesn't have to install anything. Check that it still works; a dead link undermines the rest of the page. If you can't host it, a screenshot or short GIF of the main screen helps.

Add a short Known limitations section. For example: "Search only matches exact city names" or "No tests yet for the forecast view." This isn't admitting failure. It shows you understand your own project and saves the reader from discovering the gaps and wondering whether you noticed them.

A brief What I learned or Next steps section also gives useful signal about how you think.

Test it like a stranger

You can't judge your own README, because you already know everything it leaves out. Test it instead:

1. Clone your repository into a brand-new folder.
2. Follow the README literally, typing only what it says.
3. Every time you have to use knowledge that isn't written down, like a missing command, an unmentioned environment variable, or a required Node version, fix the README.

Even better, ask a friend to follow it while you watch without helping. Wherever they hesitate is a gap. It takes ten minutes and catches problems that rereading never will.

What to do now

Write or rewrite the README for the project you just put on GitHub:

1. Open with one or two sentences on what it does and why you built it.
2. Add a live link or screenshot near the top if you have one.
3. Write prerequisites and exact copy-pasteable setup commands, plus a .env.example if needed.
4. Add a short tech stack section and an honest known-limitations section.
5. Clone the repo into a fresh folder and follow the README word for word, fixing every gap you hit.

Then you'll have something concrete to ask for feedback on.