GitHub Profile & README Evaluation Checklist
Use this to review your own GitHub — or someone else’s — before sharing it with employers.
Profile Level:
| Check | Why it matters | |
|---|---|---|
| ☐ | Profile photo | Makes it feel like a real person, not a bot |
| ☐ | Bio is filled in | 1–2 lines on who you are and what you’re looking for |
| ☐ | Location set (at least country) | NZ employers look for local candidates |
| ☐ | LinkedIn or portfolio URL linked | Easy way to find more about you |
| ☐ | At least 3 repos pinned | Controls what employers see first |
| ☐ | Pinned repos have descriptions | That one-line description under the repo name matters |
| ☐ | Profile README exists | The special repo that shows on your profile page — not everyone knows about this |
📁 Repo Level (run this for each pinned repo)
| Check | Why it matters | |
|---|---|---|
| ☐ | Repo has a README | Without this employers have no context |
| ☐ | README explains what the project does in plain English | Not everyone reading it is a developer |
| ☐ | README explains who it’s for / the problem it solves | Context > code |
| ☐ | Tech stack is listed | Employers and recruiters scan for this |
| ☐ | Has a live URL or demo link | A working link is worth 10x a screenshot |
| ☐ | Has at least one screenshot or image | Visual context makes a huge difference |
| ☐ | Setup/installation instructions included | Shows professionalism and consideration for others |
| ☐ | Known limitations or future plans noted | Shows self-awareness and forward thinking |
| ☐ | Commits are meaningful, not just “fix” or “update” | Shows how you think and work |
| ☐ | Repo description (the one-liner at the top) is filled in | Often skipped, always worth doing |
📝 README Quality Scale
Use this to give a quick score when reviewing in pairs:
Level 1 — Empty or placeholder
No README, or just the auto-generated one GitHub creates. Employer/viewer just sees raw code with no context. 🚩
Level 2 — Title only
Has a README but just names the project, no explanation of what it does or why. Still a 🚩
Level 3 — Basic description
Explains what the project is in 1–2 lines. Better, but no problem statement, no tech stack, no visuals. Getting there.
Level 4 — Solid
Has details of: what it is, who it’s for, tech stack, a screenshot or link, and some setup notes. This is the minimum bar for a job application. ✅
Level 5 — Standout
Has everything in Level 4, plus: a clear problem statement, process or decisions explained, known limitations, and what they’d do differently. Tells a story. Employer reads this and wants to meet them.
Quick Gut-Check Questions
After reviewing a repo, or looking at yours from an objective perspective, ask yourself:
- If I knew nothing about this person, would I understand what this project does?
- Can I see their thinking, or just their code?
- Is there something here I could ask them about in an interview?
- Does this make me want to see more of their work?
If the answer to any of these is no — that’s your feedback, and starting point for improvements.
The Most Common Fixes (in order of impact)
- Add a screenshot — single biggest visual improvement, takes 2 minutes!
- Write a one-paragraph problem statement — why does this project exist?
- Add a live URL — deploy it, if it isn’t already.
- Fill in the repo description — the one-liner at the top right of the repo.
- Pin your best 3–6 repos — don’t let employers land on an old, abandoned project!
- Write a profile README — a small, personal touch that most students skip
Peer Review Sentence Starters:
For giving feedback to each other without it feeling awkward:
- “I wasn’t sure what this project was for until I got to…”
- “The thing that would make this stronger is…”
- “I’d love to know more about why you chose to…”
- “This is already working well — the one thing I’d add is…”