A README that makes people open the project

Why it matters

The README is the first thing anyone sees. If it's missing or empty, the code usually goes unlooked at: it isn't clear what this is, why, or how to run it.

It's the cheapest fix in a portfolio: half an hour's work, and an enormous difference between your project being opened or closed.

What to write, in order

1. What it is, in one paragraph. In plain language, no jargon. "A service that tracks expenses from photos of receipts: upload a picture and the amount lands in the monthly report."

Test: would someone outside your field understand it?

2. A link to see it. A working one. At the top, not the bottom.

3. A screenshot or short screen recording. One picture explains more than three paragraphs, especially with an interface.

4. How to run it. Commands that genuinely work on a clean machine. Test on another device — something is almost always missing.

5. What it's built from. The technologies, and briefly why those. The second matters more than the first: a justified choice shows you were thinking.

6. How it's arranged inside. A couple of paragraphs on how the pieces connect, so nobody has to guess which file to start with.

7. What's next. What's missing, what you plan. Often skipped, and it shows you can see the weak spots in your own work. That counts.

What to leave out

• Copies of the documentation for libraries you used.
• Empty headings left over from a template.
• Boasting. "A unique service with no equivalents" has the opposite effect.
• Ten screens of text. People read the first two.

On team projects

If it was built together, say who did what. Not as a formality: without it the reader can't tell which part was yours and, at best, assumes the worst.

The phrasing is simple: "Ivan — data and processing, Maria — interface, Pyotr — deployment and build". One line that answers the main question about any team project.

Better still when contributions are described not by the participants themselves but by whoever ran the project: then it stops being self-presentation and becomes testimony.