How to write a README that recruiters actually read

A recruiter or interviewer gives your project about a minute. In that minute they read the README, not your code. If the README is empty, or just says "My project", most people close the tab. If it's clear, they scroll down and look at your work.

Here's how to write one that earns that scroll.

Answer five questions, in this order

1. What is it?

One or two sentences, in plain words. Who is it for and what does it do?

BusPass lets students at my college book and renew their bus passes online instead of queuing at the transport office.

Not "A MERN stack project". The stack comes later.

2. Can I see it?

A screenshot, a short GIF of the main flow, or a live link at the very top. Proof beats description. If the project is deployed, say so in the first lines: Live demo: link.

3. How do I run it?

Exact commands that work on a fresh machine:

git clone https://github.com/you/buspass.git
cd buspass
npm install
cp .env.example .env    # then fill in the values
npm run dev

Include the versions you used (Node 22, Python 3.12…) and any setup steps, such as creating a database. If someone follows your steps and it doesn't run, they assume the project doesn't work.

4. What did you build, and what did you decide?

• The main features, as a short list.
• The stack, with one reason for each important choice: "Postgres because bookings and payments need transactions", "server-side validation so the form can't be bypassed".
• How you tested it, even if it's only a few tests.

This section is what interviewers ask about. Writing it down prepares your answers.

5. What are the limits, and what's next?

Every project has limitations. Saying "no email notifications yet; passwords use the provider's default policy" shows judgement. Hiding them doesn't.

A template you can copy

# Project name

One or two sentences: what it does and who it's for.

**Live demo:** https://… · **Video walkthrough:** https://…

![Screenshot of the main screen](docs/screenshot.png)

## Features

- …
- …

## Run it locally

1. Requirements: Node 22 / Python 3.12 / …
2. `git clone …`
3. `…install…`
4. Copy `.env.example` to `.env` and fill in the values
5. `…run…`

## How it works

- Stack: … (why: …)
- Key decision: … (why: …)
- Tests: how to run them, and what they cover

## Limitations and next steps

- …

## Licence

MIT

Small things that make a big difference

• Use real headings and lists. A wall of text is skipped.
• Keep secrets out. Commit a .env.example with placeholder values, never the real .env.
• Fix broken images and dead links. They make the whole project look abandoned.
• Say what's yours. If you started from a template or tutorial, link it and list what you changed. Honesty here builds trust; reviewers can tell anyway.
• Update it when the project changes. An outdated README is worse than a short one.

Then show you understand it

The best README in the world doesn't replace being able to explain your project. A good test: can you walk someone through the README and the main file in three minutes, out loud? Record yourself doing it once. It's the best interview practice there is, and a short walkthrough video linked in the README is strong proof that the work is yours.