A recruiter or engineer lands on your repository. They will give it about fifteen seconds before they decide whether to keep reading, open the live link, or close the tab. Everything about that decision happens in the README — and most READMEs are either the auto-generated Create React App text or a single line that says "college project".
You do not need a long README. You need one that answers four questions in order, fast.
The four questions, in order
1. What is this? (one sentence)
Not "a web application built using the MERN stack". That describes ten million repositories. Say what it does for whom: "Splits a hostel mess bill across roommates from a photo of the receipt." The tech stack goes further down; nobody chooses to open a project because it uses Express.
2. Can I see it? (a link, and a picture)
A live URL in the second line. If it is deployed, that link is the single most valuable thing in the file. Under it, one screenshot or a short GIF of the main screen. People open things they can picture.
If it is not deployed, deploy it. Free tiers on Vercel, Railway, Render, or GitHub Pages cover almost anything a fresher builds, and "runs on my laptop" is not something a reviewer can check.
3. What was hard? (three to five lines)
This is the part almost everyone skips and the part reviewers actually care about. Every project has one decision that cost you a day. Write it down: what the problem was, what you tried, what you chose, and why.
"Receipts photographed at an angle broke the line-item parser. I tried three OCR settings before switching to grouping by y-coordinate, which handles tilt up to about 15 degrees. Beyond that it asks the user to retake."
That paragraph tells a reviewer more about how you think than the rest of the repository combined. It also becomes the answer to the first question in your interview — here is the script.
4. How do I run it? (copy-paste commands)
Clone, install, environment variables, start. Four commands, tested on a clean machine. If you need an API key, say which and where to get it. If a step is missing, the reviewer's first experience of your code is an error message.
The template
Paste this at the top of your project and fill in the blanks. Delete any section you cannot fill honestly.
- Line 1: project name — one sentence on what it does and for whom.
- Line 2:
Live: https://...— and a screenshot or GIF underneath. - Section: What it does — three to five bullets, each a thing a user can do.
- Section: The hard part — one paragraph, as above.
- Section: How it works — the stack and a two-line explanation of the architecture. A small diagram helps if there is a moving part worth explaining.
- Section: Run it locally — the commands.
- Section: What I would do next — two or three honest bullets. Shows you know where the edges are.
- Section: Credits — anything you learned from or borrowed. Reviewers respect this; they distrust its absence.
Things to leave out
- Badges you did not earn. A row of shields for build status and coverage on a project with no tests reads as decoration.
- The tutorial's text. If the README still says "This project was bootstrapped with…", nobody believes the project was not bootstrapped with it too.
- A "Technologies used" wall of logos. The stack belongs in one line of the How it works section.
- Motivational prose. "In today's fast-paced world…" costs you the fifteen seconds.
Match the README to the repo
A README that promises features the code does not have is worse than a short one. Reviewers who care will open the files, and a mismatch between the description and the code reads as either copied or inflated — see what reviewers actually check. Describe what exists today. Put the rest under What I would do next.
On Iber
When you post a build on Iber, the two-minute demo and the repository sit next to each other, and the interview asks about the decisions in the code. A README written the way above makes all three easier: the demo follows the same four questions, and The hard part paragraph is your first interview answer, already written.
Checklist before you push
- First sentence says what it does for whom.
- Live link works in a private window.
- There is a screenshot.
- The hard part is written and true.
- The run commands work on a machine that is not yours.
Fifteen seconds is not much. This is how you spend it well.