I spent the last few months looking at developer portfolios more closely than anyone should reasonably want to.
I was building a tool that helps developers create and maintain portfolio sites. To make decisions about it, I read through hundreds of real portfolio pages, talked to developers about why they made the choices they made, and read everything I could find about how recruiters and hiring managers actually use these pages.
What I learned was not what I expected.
Most developer portfolios are not bad because the developer can't design. They're bad because they're answering the wrong question.
The developer thinks the portfolio is asking: "what can I do?"
The recruiter is actually asking: "can I trust this person to ship?"
Those are different questions and they need different answers. The portfolios that get developers hired answer the second one. Most portfolios I see are still trying to answer the first.
Here are the patterns I keep seeing, why they hurt, and what to do instead. None of this requires more design skill. Most of it requires less.
Mistake 1: opening with a hero section that says nothing
The most common portfolio opener I see is some variation of:
Hi, I'm Alex. I'm a passionate full-stack developer who loves clean code and learning new technologies.
This sentence appears, with minor variations, on roughly half of every portfolio I've looked at. It says nothing. Every developer applying for the job is passionate. Every developer claims to love clean code. The recruiter has read this sentence 400 times this week.
The opener is the most expensive real estate on your portfolio. If a recruiter is going to bounce after 7 seconds, they're bouncing from your opener. Treat it like a headline, not a greeting.
What works better is being specific about what you actually do and who you do it for:
I build React apps for fintech startups. The last three I shipped handled regulated payment flows.
You can read that and immediately know whether to keep reading. The first version made you wait for the projects section to find out.
The fix is one sentence. Replace passion-and-adjectives with what-and-for-whom.
Mistake 2: listing every technology you've ever touched
The skills section is usually a wall of logos. React, Vue, Angular, Svelte, Node, Express, Django, FastAPI, MongoDB, PostgreSQL, Redis, AWS, GCP, Azure, Docker, Kubernetes, Terraform, and so on.
This looks impressive for about two seconds and then becomes suspicious. Nobody is really expert in 30 technologies. Listing them all signals one of two things to a recruiter: either you don't know what you don't know, or you've touched each of them once in a tutorial and you're padding.
The developers who get the senior roles do something different. They pick four or five technologies they're actually strong in and put those in the header. Everything else either goes in a smaller "have used" section or doesn't appear at all.
The counterintuitive truth is that a shorter skills list reads as more experienced, not less. Saying "I work mostly with React and Node, with some Go" reads as someone who has a primary stack. Saying "React, Vue, Angular, Svelte, Solid, Qwik" reads as someone who has tried a lot of tutorials.
If you're early-career and worried that a short list looks thin, you're solving the wrong problem. The recruiter isn't comparing your list to someone else's longer list. They're comparing your list to the role's requirements. Match the requirements with depth, not breadth.
Mistake 3: projects that don't say what they do
This is the one that loses the most opportunities and it's the easiest to fix.
Most portfolio projects look like this on the page:
MyApp
A full-stack web application built with the MERN stack.
[Live Demo] [GitHub]
That description tells the recruiter exactly nothing. They have to click through to figure out what MyApp does, whether it's interesting, and whether it relates to the work they're hiring for. Most won't click. They'll just move on.
A project description needs to answer three questions before the recruiter has to click anything: what does it do, what problem does it solve, and what about it is technically interesting.
Compare:
MyApp: A full-stack web application built with the MERN stack.
versus:
MyApp: A peer-to-peer book trading app for a local reading community. 600 users, 2,000 trades. The interesting part is the matching algorithm that pairs books by genre and proximity in a single query.
The second version is the same project but it has actually said something. A recruiter scanning your portfolio in 7 seconds now has a reason to care.
The fix is two or three sentences per project. What it does, who uses it, what about it is technically interesting. If the project doesn't have a technically interesting part, leave it off the portfolio.
Mistake 4: not showing the work, only the result
Most portfolios link to a deployed app and a GitHub repo. That's it. The deployed app shows the result. The GitHub repo shows the code. Neither shows the work.
The work is the part where you decided why to build something this way and not that way. The work is where you fixed the bug that took three days to track down. The work is the thing recruiters actually want to see because it's the only thing that signals whether you can handle a real production codebase.
The portfolios that stand out, in my experience, are the ones that include a few paragraphs of context per project. Not a sales pitch. Just: what were the constraints, what tradeoffs did you weigh, what would you do differently now.
This doesn't have to be a separate blog. It can be a "build notes" section on the project page itself. A README in the GitHub repo that's actually thoughtful counts. A short video walking through the architecture counts. Anything that surfaces the thinking behind the build, rather than just the build itself, is worth more than another logo on your skills section.
I built getfolio.dev partly because this was the workflow I wanted for my own portfolio. I wanted somewhere to write the build notes alongside the projects, sync them from GitHub automatically so they don't go stale, and have it all live on a real public URL. But you don't need a tool for this. You just need to write the notes. Most developers don't, which is exactly why writing them is a differentiator.
Mistake 5: the portfolio that hasn't been updated in 2 years
This is the silent killer.
Almost every portfolio I've read had something on it that betrayed its last update date. A "currently learning Vue" tag, a featured project from 2022, a copyright year that hasn't been touched. None of these are critical mistakes individually. Together they tell the recruiter: this person built a portfolio once and hasn't thought about their career since.
That is the worst possible signal. The implicit message is that the developer either doesn't ship anything new worth showcasing, or doesn't care enough to surface what they do ship.
The fix is not "update your portfolio more often." That has never worked for anyone. The fix is structural: build the portfolio in a way that updates itself. Pull projects from GitHub so new ones appear automatically. Pull blog posts from wherever you already write. Pull contribution data so it stays current without you touching it. The portfolio that maintains itself is the portfolio that stays alive.
If you're going to manually update anything, manually update the opener and the featured project descriptions. Those need editorial judgment. Everything else should be on rails.
Mistake 6: a contact section that costs the developer the job
This one shows up less often than the others but when it shows up it's catastrophic.
A contact section that says only "feel free to reach out" with a contact form is a contact section that loses opportunities. Recruiters work with email. They will not fill out a form. If your only contact method is a form, you've filtered out the people who were most likely to hire you.
Same with "let's connect on LinkedIn." LinkedIn DMs are not how senior recruiters and hiring managers reach out. Email is.
The fix is one line: put a real email address on the page, visible, copyable. Add LinkedIn and GitHub next to it. That's all. The "I'd rather not get spam" instinct here costs more than the spam ever would.
What actually works, in one paragraph
The portfolios that get developers hired are short, specific, and current. They open with one sentence that says what you do and for whom. They list four or five technologies in depth instead of thirty in breadth. They describe each project in two or three sentences that include what it does, who uses it, and what's technically interesting. They include some signal of thinking, like build notes, decisions, or tradeoffs, alongside the deployed result. They update themselves wherever possible so they don't go stale. And they let recruiters reach out by email.
Nothing here is hard. Nothing here requires a designer. The portfolios that win are not the prettiest ones. They're the ones that took the recruiter's actual question seriously and answered it directly.
The good news is that the bar is low. Most portfolios I've looked at fail at most of these. Fixing even half of them puts you in the top ten percent of what recruiters see this week.
That's worth a Saturday afternoon.
I write about developer tools and what I'm learning building getfolio.dev, a developer portfolio platform that auto-syncs with GitHub. If this resonated, the writing on the homepage probably will too.
Top comments (0)