A reader named Gautam put it better than I did, in a comment on my own article: the README is the only writing sample a reviewer gets for free.
I had just published a tally of 30 beginner job ads, counted word by word over two evenings. He read it, thought about it for a minute, and found the connection I'd walked straight past. So this piece is his point, developed, with the numbers underneath it.
The numbers, once more
Out of 30 ads aimed at beginners:
Git or GitHub used on a real project showed up in 26. One language or framework done properly, 24. A finished project you can show, 21. Clear writing — docs, updates, emails — 18. A long list of languages at once, 4. Certificates named specifically, 2.
That writing row is the one people skip. Eighteen out of thirty ads asked for it, more than four times as many as asked for breadth of languages. And here's Gautam's insight: when a reviewer clicks your project, they don't have to take your word for any of it. The commit history is the Git row, checked in a minute. The README is the writing row, checked in the same visit, without emailing you, without scheduling anything. It's an interview you give while asleep.
What those 18 ads are actually buying
Nobody hires a beginner because they dream of reading their documentation. The writing ask is a proxy for something harder to test: can this person explain a problem to someone who wasn't in the room?
That's most of the job once you're inside. The build is late and someone has to say why, in a message, clearly enough that nobody needs a meeting about the message. A bug turns out to be weirder than expected and the next person needs your notes, not your memory. "Must be able to explain your work" kept appearing in those ads in different costumes — standups, tickets, updates to people who don't code. The README is simply the earliest place a stranger can watch you do it.
A reviewer knows this, even if they've never said it out loud. A repo with a thoughtful README reads like a person who will write thoughtful tickets. A repo with the default template still in it reads like the opposite, fair or not.
What a beginner README should actually contain
Four things. Not forty.
What it does, in two or three plain sentences, before any setup instructions. If a stranger can't tell what the project is by the second paragraph, the interview is already going badly.
Why you made the choices you made. Not a technology list, the reasoning. Why this framework and not the obvious alternative. Why a file instead of a database. This is the section that turns a tutorial clone into evidence of thought, and it's the section almost nobody writes.
How to run it, exactly. The real commands, in order, including the embarrassing step everyone forgets, like the environment variable or the seed file. If the reviewer can't run it, your finished project is a photograph of a finished project.
What broke. One short paragraph on the bug that cost you the most time and what it turned out to be. This does two jobs: it proves a real person built the thing (tutorials don't have bugs with histories), and it's the best writing in the whole document, because it's a story with a villain.
Before and after, on an imaginary project
This example is invented, a little weather app of the kind a thousand of us have built. Before:
# weather-app A weather app built with Python and Flask. ## Installation pip install -r requirements.txt python app.py Nothing is false there. It also says almost nothing, and a reviewer learns only that the author can operate a template.
After:
# weather-app Shows the next 12 hours of weather for one city, on one page, with no account and no JavaScript. I built it because every weather site I tried needed three clicks to answer one question. ## Why it's built this way Flask, not Django — the app has two routes and Django's admin, auth and ORM would be furniture in an empty room. Forecasts come from the Open-Meteo API because it needs no key, so anyone can clone this and run it without registering for anything. ## Run it pip install -r requirements.txt python app.py Then open localhost:5000 and type a city name. ## What broke For two days the temperatures were 6 degrees off. I blamed the API, then my timezone maths. It was neither: I was requesting Fahrenheit and displaying the number next to a °C label. The fix was one word in the request URL. The debugging took longer than building the app did. Same project. Same author. The second one answers questions a reviewer was going to have anyway: Does he finish things? Can he explain a decision? Can he write a paragraph a stranger can follow? Three of the scoreboard's rows, settled before a single interview question gets asked.
The honest catch
A README won't rescue an empty repo, and I should say plainly that my tally was 30 ads, skewed toward remote, English-language postings. It's a signal, not a census. But the direction is hard to argue with: the ads asked for proof over claims, and a README is the cheapest proof to produce. It costs an evening. The project it describes probably cost weeks. That ratio is absurd, and most of us still leave the template in.
So, over to the people who read these for a living, and the people who write them. What's the best README you've ever landed on — the one that made you trust a project in under a minute? And beginners: when did you last read your own README as if you were a stranger deciding whether you're worth an interview?
P.S. Everything I write stays free — that part doesn't change. But if this one was worth something to you, you can buy me a coffee ☕ (one-time or monthly, both work). It covers the API credits and hosting behind these experiments — and honestly, it's also the nudge that gets the next one started on the evenings I'd otherwise skip it. — Salam
