The README is the door to your project. It's the first thing reviewers open, and the first thing voters read when deciding whether to try your demo. It's also almost always the easiest part of your project to upgrade in a single afternoon.
Here's a structure that works, in order, with notes on why each piece matters.
The structure that works
1. Title + one-sentence description
Top of the file. The title is your project's name. The next line is one sentence describing what it is. Not what it does internally — what it is, to a human who has never heard of it.
FitTrack
A REST API for fitness enthusiasts to track workouts, body metrics, and personal records.
Bad version of the same:
FitTrack
This is my Stardance project! I made an API using FastAPI and SQLModel.
The bad version tells the reader about you. The good version tells them about the thing.
2. Hero image, GIF, or screenshot
One image, right after the description, showing the project in action. People skim. An image converts a skim into curiosity faster than any sentence.
For different project types:
- Web / app / mobile — a clean screenshot, ideally a GIF showing the main flow.
- CLI — an asciinema cast or animated GIF of a real session.
- Hardware — a photo of the assembled thing. Renders are second-best.
- Game — gameplay GIF or a key art frame.
3. The "try it" link
A link to your live demo. Same URL as your demo URL field, repeated here because some people land on the README first. Make it impossible to miss — bold, link, ideally a button-style image.
4. Quick start
How does someone go from "I want to try this" to "I am trying this"?
- For web: usually just "open the link." Done.
- For CLI: the install command, in a code block, copy-paste-runnable.
- For libraries: the import statement and a 5-line example.
- For games: download link + how to launch.
If your quickstart is more than three commands, you've made onboarding too hard. Look for what you can default, prebuild, or cut.
5. Features
A bullet list of what the project actually does. Not a marketing pitch. Specific, scannable, ideally each bullet is something a voter could verify in your demo.
Aim for 3–7 bullets. Fewer feels thin; more becomes a wall of text nobody reads.
6. How to run it locally (if applicable)
For anything other than a deployed-only website, include real local dev instructions. Voters and reviewers shouldn't have to guess at npm install vs yarn vs pnpm.
Things to spell out:
- Required language version (Node 20, Python 3.11, etc.).
- System dependencies that aren't language-managed (ffmpeg, postgres, etc.).
- Environment variables, with example values.
- The exact command to start it.
7. How it works (optional but recommended)
A paragraph or two on the interesting technical choices. This is where you give voters a reason to score "technical depth" highly. Don't just list libraries — explain a decision or a tradeoff.
Bad: "I used React, Tailwind, and Postgres."
Good: "The diff visualization runs entirely client-side using Web Workers, because the projects we benchmark on have files large enough that a main-thread parse stalled the UI."
8. Credits / acknowledgements
Anyone who helped, libraries you leaned on heavily, asset packs you used. Two reasons: it's the right thing to do, and it signals that you've spent time around real open-source projects.
Common mistakes
- The placeholder README from a starter template. Reviewers see thousands of these — the boilerplate "This project was bootstrapped with…" intro is an instant tell. Replace it.
- "This project is for Stardance!" as the entire description. The README is for visitors who don't know what Stardance is.
- No images. A wall of text without a single screenshot loses most skimmers in the first few seconds.
- Setup instructions that worked on your machine three months ago and have rotted. Test them again before shipping.
- A "demo" link that's just the GitHub repo. Already covered in What does shipping mean? — but it bears repeating.
One trick
Open someone else's project that you genuinely admire. Look at how their README opens — the first three lines, the first image, the first link. Steal the structure. The good ones converge on the same shape because that shape works.