README Quality
README Quality looks at how well your README documents your project and reflects on what you learned building it. A clear README helps the lessons stick and makes your work easy for anyone to follow.
Table of contents
How it works
README Quality is one dimension of your AI code review, under the Documentation category. We read the README in your repository and look at how well it documents this project and reads as a learning journal.
We recommend writing a good README rather than requiring it, so this dimension is here to encourage the habit and help you build it early. It's reviewed on every challenge, from Newbie to Guru.
What makes a strong README
Most strong READMEs cover a few things:
- a short overview of the project and what it does,
- a screenshot of your finished solution,
- the technologies you built it with,
- links to the live site and the challenge,
- and a few notes on what you learned, what you found tricky, and what you'd build next.
The reflective part is the heart of it. Notes tied to the actual work ("I finally understood CSS grid minmax() while building the gallery") are worth far more than generic lines like "I learned a lot about CSS."
Why it's worth it
Documenting a project pays off in a few ways, even on practice builds:
- It helps you. Writing up what you built and what you learned helps it stick, and gives you a clear record to look back on when you return to the project later.
- It helps the people reviewing your code. A clear README gives a peer or mentor the context to understand your project quickly, so the feedback you get back is more useful.
- It's a green flag on your GitHub. As your solutions become portfolio pieces, good documentation shows anyone reviewing your work how you think, the decisions you made, the challenges you worked through, and how you collaborated with AI to get there.
A head start with the template
Every Frontend Mentor challenge ships with a README-template.md file in the starter code. Rename it to README.md, then fill in each section with your own project details. It gives you the structure, so you can focus on the content.
Make it your own. A template left with its placeholder prompts and example text still reads as unwritten, so swap in real details about your solution.
How difficulty changes the bar
We calibrate README Quality to the level of the challenge, so the bar rises as you take on harder work.
- Newbie and Junior: a clear description of the project and a screenshot is a great start. A sentence or two of reflection is a welcome bonus.
- Intermediate: a clear overview, a screenshot, your "built with" list, links to the live site and challenge, and a real reflection on what you learned.
- Advanced and Guru: a genuine learning journal, with specific reflections on what you learned and found challenging, plus ideas for what you'd develop next.
These are solutions you'll want to show off, so a strong README matters more as you go, though it stays a recommendation the whole way up.
Improving your score
- Start from the template, then replace every section with your own project details.
- Add a screenshot of your finished solution.
- Write a few honest lines about what you learned and what tripped you up. This is the part that helps you most.
- Include links to the live site and the challenge so anyone can see your work in context.
Even a short, genuine README beats a long, untouched template. Write it as you would explain the project to another developer, and your README Quality score will follow.