Your README is your first interview

I've evaluated a lot of repositories — my own old ones, contributors' work, projects I consider joining. The README decides the verdict before the code loads. Not because READMEs matter more than code, but because they're the first signal of how someone thinks.

The five-part README that works

1. One sentence: what it is. Not a paragraph. A sentence.
2. Why it exists. The problem, in one or two lines. If you can't state the problem, the solution will confuse everyone.
3. How to run it. Copy-pasteable commands that actually work on a clean machine — which means you tested them on a clean machine.
4. What it looks like. One screenshot or demo GIF. Honest ones, not the beauty-shot from the one configuration that works.
5. Limits. What it doesn't do. Every serious project knows its boundaries; pretending you have none is how readers know you haven't finished thinking.

The tells of a weak README

Walls of badges with no sentence. "Installation: coming soon." A features list with no usage. It signals a project built for the author's pride, not the reader's next step.

The reframe that helped me: a README isn't documentation of the code. It's a promise to the next person — often future-you — that this project respects their time.