TD
Key Takeaways
- A broken link or dead deployment is worse than having no portfolio, because you invited the check and it failed.
- Reviewers spend ninety seconds, so anything requiring exploration to understand is lost.
- Showing output without reasoning is the most common substantive failure.
- Too many projects is a worse problem than too few, because it dilutes your strongest work.
- Slow loading and broken mobile layouts eliminate you before content is assessed.
Portfolios rarely fail because of how they look. They fail because a link does not work, because a reviewer cannot tell what a project was for, or because there are twelve projects and the good one is fourth.
These are all fixable in an afternoon, and most people never audit for them.
This guide is the audit.
Start with the document that gets people to your portfolio at all — the free ATS score checker.
Things that eliminate you before content
A dead link. The single worst failure. You put a URL on your resume, a reviewer clicked it, and it 404'd or timed out. That is worse than no link, because you invited the check.
A sleeping deployment. Free hosting tiers frequently spin down after inactivity, and a project taking thirty seconds to wake has already lost the reviewer. Check yours during the job search rather than assuming.
Slow loading. Large unoptimised images are the usual cause. Reviewers on mobile with poor connections leave.
Broken on mobile. A meaningful share of reviewers open links on a phone. A layout that breaks there eliminates you before anything is read.
A project that errors on load. Test everything you link, from a browser you are not logged into.
Requiring login to view. If a reviewer must create an account, they will not.
The failures you cannot see from your own laptop
Every one of these looks fine to you and broken to a reviewer, which is exactly why they survive so long.
| What breaks | Why you never notice | How to catch it |
|---|---|---|
| Project needs your login | You are permanently signed in | Open in a private window |
| Repo is set to private | You can see it; nobody else can | Log out and open the link |
| Free tier has spun down | You visited it recently, so it was warm | Check after not touching it for a week |
| Images take 20 seconds | Your machine cached them | Private window, mobile data, not wifi |
| Layout breaks under 400px | You only ever view it at desktop width | Open it on your actual phone |
| Local API the site calls | It runs on your machine | Open it on your phone, not your laptop |
| Custom domain expired | You have the old URL bookmarked | Type the URL on your resume, character by character |
| Link works but resume PDF's does not | You test the site, not the document | Click the link inside the exported PDF |
The last row is the one that catches most people. The portfolio is fine. The link on the resume was never clickable, or points at a typo of the real address.
Things that waste the reviewer's time
No context on what a project is. A screenshot with no explanation forces the reviewer to work out what they are looking at, and they will not — see portfolio case study writing.
Burying the outcome. Put what happened near the top. Reviewers scan.
Requiring navigation to understand. If the homepage does not communicate what you do within a few seconds, the structure is wrong.
A long personal statement first. Nobody reads three paragraphs about your passion before seeing any work.
Twelve projects. More is worse. Reviewers look at the first two, so eight weak entries actively bury your strongest — the same curation principle as side projects on your resume.
Substantive failures
Output with no reasoning. The most common real problem. Showing what you built proves it exists; explaining why you built it that way proves you made decisions, which is what is actually being assessed.
No constraints mentioned. Work with no budget, timeline or technical constraint reads as academic. Constraints are what make decisions interesting.
Vague role on team projects. "Worked on the redesign" tells a reviewer nothing. State what you personally owned — ambiguity is read unfavourably.
No numbers. An improvement without a measure is an assertion.
Everything presented as flawless. Naming a genuine misstep and what you changed is the strongest credibility signal available, and almost nobody includes it.
Tutorial projects presented as original. A to-do app or a well-known clone is recognisable immediately. Extend at least one beyond what the tutorial did — see choosing a final year project for placements.
Presentation failures
Design that fights the content. Unusual navigation, animations that delay reading, low-contrast text. Creativity in the frame rather than the work is a common trap for designers particularly.
Inconsistent quality. One strong case study next to four thin ones drags the average down. Remove the weak ones.
Typos. In a document you controlled entirely, they read as carelessness.
Stale content. A portfolio last updated three years ago raises questions about what you have done since.
No contact information, or contact details that are hard to find.
Numbers inconsistent with your resume. A metric stated differently in two places undermines confidence in both — see portfolio vs resume.
The audit
Do this once and it catches almost everything. Twenty minutes.
1. Open your portfolio on your phone, on mobile data rather than wifi, in a private browsing window. This single step catches the login, private-repo, caching, spun-down and mobile-layout failures at once.
2. Count the seconds until the homepage is readable. Over five, find the largest image and shrink it.
3. Click every link — every project, every repository, every demo, plus the contact links. From that same private window.
4. Open your resume PDF and click the portfolio link inside it. Not the site, the link in the document. This is the most commonly broken thing in the entire chain.
5. Send it to someone outside your field and ask two questions after two minutes: what do I do, and which project was strongest? If they cannot answer, the problem is structure rather than work.
6. Check every number against what your resume claims. They must match exactly.
7. Read it for typos on a different day from the one you wrote it on.
8. Confirm your contact details are correct, current, and findable without scrolling.
Common Mistakes
Linking something that does not work. A dead link or a sleeping deployment is worse than no link, because the reviewer checked at your invitation.
Only ever testing while logged in. Private repos and login-gated projects look perfect to you and are invisible to everyone else.
Ignoring mobile. A substantial share of reviewers open portfolio links on a phone, and a broken layout eliminates you before content is read.
Never clicking the link inside the resume PDF. The site can be perfect while the link that points to it was never clickable.
Showing output without reasoning. It proves the work exists but not that you made decisions, which is what is being assessed.
Including too many projects. Reviewers look at the first two, so weak entries bury your strongest work rather than adding to it.
Being vague about your role. On team projects, unclear contribution is read as minimal contribution.
Presenting everything as flawless. A genuine misstep with what you changed afterwards is the strongest credibility signal you can offer.
Letting it go stale. A portfolio untouched for years raises questions about what you have done since.
Numbers that disagree with your resume. A metric stated two ways undermines confidence in every other claim.
Frequently Asked Questions
What is the single worst portfolio mistake?
A broken link or a deployment that does not load. It is worse than having no portfolio, because you invited the reviewer to check and the check failed.
Why does my portfolio work for me but not for reviewers?
Usually a login, a private repository, or browser cache. Open it in a private window on mobile data and the difference is immediate.
My free hosting keeps sleeping. Does that matter?
Yes. A thirty-second cold start loses the reviewer before anything loads. Keep it warm during an active search, or move to hosting that does not sleep.
How many projects should I include?
Two or three explained properly. Reviewers rarely go past the second, so additional weak entries bury your strongest work.
Does mobile really matter?
Yes. A meaningful share of reviewers open links on a phone, and a layout that breaks there loses you before anything is assessed.
Should I include work I am not proud of?
No. Inconsistent quality drags the average down, and curation is itself a signal.
Do I need to show failures?
Including a genuine misstep and what you changed is the strongest credibility signal available, and almost nobody does it.
How often should I update it?
At least when you change roles or complete something significant. A portfolio years out of date raises questions.
What if my best work is confidential?
Generalise the client and use relative figures, or use older or personal work — see portfolio for non-tech roles for handling this.
The resume is what gets people to your portfolio. Check your ATS score free.
Make This Practical
Open your portfolio right now on your phone, on mobile data, in a private browsing window. That one step catches the private repository, the login wall, the cached images, the sleeping deployment and the broken mobile layout simultaneously — and every one of those looks perfect from your own laptop.
Then open your resume PDF and click the portfolio link inside the document itself. Not the site. The link. It is the most commonly broken thing in the whole chain and almost nobody checks it, because testing the website feels like testing the link.
Finally, cut rather than add. Keep your two or three strongest pieces and delete the rest, then for each survivor state the constraint you worked within, what you personally owned, the measured outcome and one thing you would do differently — and make every number match your resume exactly.
See what your portfolio could look like
This theme is built straight from your resume — pick one and your portfolio is live in minutes.
Was this guide useful?
Be the first to rate it.
