Almost every candidate builds their portfolio project for an imaginary reviewer who clones the repository, installs the dependencies, runs the test suite, and reads the code with interest. That reviewer does not exist. The real one opens your link between two meetings, in one browser tab, with no intention of installing anything, and decides in the time it takes to read a first screen whether to keep going.
The short version: design for a two-minute skim with no setup. That makes the README and one short decision write-up the actual artefact, and the code the supporting evidence. One project taken to real depth beats five shallow ones, a live URL or a recorded run beats installation instructions, and the single most persuasive thing you can include is an explanation of something you deliberately chose not to build.
Design for the reviewer you actually get
Three assumptions to design against. They are conservative on purpose, and none of them are cynical about reviewers; they are just how anyone with a hiring queue behaves.
Assume nobody runs it. If understanding your work requires a working local environment, most reviewers will never understand your work. Everything essential has to be visible without execution: a deployed URL, a screen recording, output screenshots, a sample report committed into the repository.
Assume the first screen is the whole review. Whatever sits above the fold of your README is the project as far as most people are concerned. If the first thing there is an installation section, you have spent your only screen on instructions nobody will follow.
Assume they are looking for a reason to stop. Not out of malice — a reviewer with forty profiles is optimising for elimination. Broken links, an empty tests folder, a last commit from fourteen months ago, and a title that does not say what the thing does are all reasons to close the tab.
The five things a reviewer can verify in two minutes
This is the checklist our mentors use when reviewing capstones, and it maps closely to what hiring panels look for in a code review portfolio.
What they check Why it matters
1. Does the README say what it does Ten seconds. If unclear, nothing else is read
in one sentence
2. Is there evidence it runs A URL, a recording, or committed output
3. Does the commit history look like Twelve commits over three weeks reads as work.
work, not a single dump One commit reads as a download
4. Do tests exist and do they test Presence is a signal. A test suite that asserts
something real nothing is a worse signal than none
5. Is one hard decision explained The only item that distinguishes a builder
from someone who finished a tutorial
Items one to four take you from "ignored" to "credible." Item five is the one that gets you the interview, and it is the item almost nobody does.
The decision write-up is the whole differentiator
Add a short section, six to ten sentences is enough; that answers three questions about your project.
What did you choose not to build, and why? "No authentication, because the point of this was the test infrastructure and auth would have consumed a third of the time for no additional signal." That sentence demonstrates scoping judgement, which is the thing every hiring manager is actually screening for and the thing no certificate can evidence.
What broke, and how did you find it? Describing a real failure you diagnosed is more convincing than any feature list, because tutorials do not contain failures. "Tests passed locally and failed in CI; it was a timezone assumption in the seed data" tells a reviewer you have debugged something.
What would you do differently at ten times the scale? This separates people who finished a project from people who understand its limits.
This section is why the phrase proof of work means something more than "I built a thing." Anyone can build a thing. The write-up is the evidence that you made decisions while building it.
Scope: about forty-five hours, not four hundred
If you are working through a 128-hour learning budget; roughly eight hours a week for sixteen weeks, as covered in which skill to learn next; spend around forty-five of those on one project. That is enough for something genuinely end to end and not enough to disappear into it for a year.
Scope it by output rather than by feature list. Decide in advance what a reviewer will see: a deployed page, a generated report, a pipeline run with a published result. Then build only what produces that. Projects fail from expanding scope, not from insufficient ambition, and an unfinished ambitious project is worth strictly less than a finished modest one because there is nothing to open.
One deep project beats a grid of five. Five shallow projects tell a reviewer you can follow five tutorials. One project with a real decision log tells them you can be trusted with work.
Pick the project from a real job posting
The best portfolio project ideas are not on lists. They are in the postings you want to apply to.
Take the pairing of skills you found appearing together in those postings; say a test framework plus a CI pipeline plus containers and build the smallest thing that demonstrates that combination working together. Then use the posting's own vocabulary in your README, because that is the language the reviewer thinks in and, incidentally, what an applicant tracking system matches on.
This also solves the relevance problem. A technically impressive project in an unrelated area is a hobby. A modest project that mirrors the job's actual stack is an argument.
Five projects to avoid
Not because they are bad exercises, but because they carry no signal; every reviewer has seen hundreds of each and cannot distinguish yours.
- The tutorial clone. If the reviewer can find the video you followed, the project evidences the video.
- The to-do app, in any framework. The canonical zero-signal project.
- Dashboards on fake data. Fabricated data means none of the hard parts cleaning, missing values, ambiguity were faced.
- The unfinished ambitious platform. A repository whose README describes what it will eventually do.
- The certificate repository. A folder of course exercises is a transcript, not a project. This is the practical end of the personal project vs certification debate: a certificate tells them you completed a syllabus; a project tells them what you do without one.
If your best work is under NDA
Common, and not a dead end. Three legitimate options.
Describe the shape without the specifics. "I built the regression suite for a checkout flow processing about 40,000 transactions a day, and cut the run from two hours to eleven minutes." No client name, no code, real numbers.
Rebuild the pattern on public data or a public site. The technique is yours even when the implementation belongs to your employer.
Write it up as a short engineering note rather than a repository. A clear 800-word piece on how you solved a specific problem is a portfolio item, and it travels further than code because more people can read it.
For open source contribution as an alternative: a small merged pull request in a real project is strong evidence precisely because someone else reviewed and accepted it. Aim for a documentation fix or a small bug rather than a feature the merge is the signal, not the size.
How to present it in an interview
When you are asked to walk through a project, the failure mode is narrating the code. Nobody wants a tour. Use four beats, in this order, and keep it under three minutes:
- The problem, in one sentence, with a number in it.
- The constraint you were working inside time, data, no access to production.
- The decision you are proudest of, and the alternative you rejected.
- The result, stated as a measurement rather than an adjective.
Then stop, and let them ask. Interviewers form their opinion in the follow-up questions, and you cannot get to those if you are still talking. Our interview preparation rounds score exactly this walkthrough on the same rubric panels use, and our technical training tracks end with two capstones built specifically to survive this kind of review.
A two-week finishing pass
If you already have a project sitting in a repository that nobody has ever asked you about, this is usually all it needs.
- Day 1. Rewrite the README's first screen: one sentence on what it does, one screenshot or a live link, then how to run it.
- Day 2. Deploy it, or record a two-minute run and link the video.
- Days 3–5. Add tests that assert something real, and get them running in CI.
- Day 6. Write the decision section: what you skipped, what broke, what you would change at scale.
- Day 7. Commit a sample of real output — a report, a log, a screenshot set.
- Days 8–10. Get one person who does not know the project to open the link and tell you what they think it does.
- Days 11–14. Fix whatever they misunderstood, then put the link in your résumé's top third and your LinkedIn featured section.
Frequently asked questions
How many portfolio projects do I need to get a job?
One that is genuinely finished and explained, plus optionally a second smaller one showing a different skill. Beyond that, quantity actively works against you, because a reviewer's attention divides across whatever you list.
Do hiring managers actually look at GitHub?
They look at what you link, and briefly. A GitHub portfolio for jobs works when the repository you link is self-explanatory on its landing page. A profile page full of forks and abandoned repositories is neutral at best.
Does a project matter more than a certification?
For demonstrating capability, yes, in almost every case. Certifications clear filters at some large employers and give you a deadline. Projects are the thing anyone can open and evaluate.
How do I show a portfolio project on my résumé?
A projects section in the top third, above employment history if the projects support your target role and your history does not. Two lines each: what it does with a number, and the technologies, with the link on the title.
Can a project be too simple?
A simple project that is finished, deployed and explained outperforms a complex one that is none of those. The complexity that matters is in the decisions you document, not in the feature count.
What if I have no time outside work?
Then the work itself is the portfolio; write up something you built at your job as an engineering note with the confidential parts removed. Forty-five hours over three months is under four hours a week, which is the realistic floor rather than the ideal.