Developer portfolio: what to include (and what to cut)
A recruiter looks at your portfolio for twenty seconds. One finished, deployed project beats ten tutorial clones. What to include, what to cut, and why the README is half the impression.
I opened a developer portfolio last week and counted twelve to-do apps. Twelve. All with the same tutorial layout, the same purple palette, the same "Add task" button. The candidate thought volume was impressive. The recruiter who looks at it for twenty seconds thinks the opposite: if they are all identical, none of them says anything. A portfolio is not a dumping ground for exercises, it is an argument about what you can do.
This piece is about what to put in that argument, what to cut without mercy, and why one finished, deployed project beats ten half-built ones.
The recruiter gives you twenty seconds, tops
Before any decision about content, internalize the real constraint: nobody is going to study your portfolio. A recruiter opens the tab, glances, and decides within seconds whether it is worth scrolling. A tech lead about to interview you might spend two minutes before the call. That is the attention budget you have.
That changes everything. It means the value has to be visible without a click. It means the first fold of the page matters more than the sixth. And it means burying your best project under three tutorial clones and a tic-tac-toe game is waste. You are not being judged on the quantity of things you have touched; you are being judged on the best thing you managed to finish and explain.
A few real projects beat many half-built ones
The unpopular opinion: two to four substantial projects beat ten mediocre repositories every time. Substantial does not mean huge. It means it solves a concrete problem, you carried it to the end, and you made at least one non-obvious technical decision along the way.
One finished, deployed and documented project communicates something ten half-built ones never can: that you can close scope. Closing scope is exactly the skill most juniors lack and the one that costs a team the most. Someone who shows a small but whole product is saying "I finish what I start". Someone who shows ten abandoned branches is saying the opposite, even without realizing it.
On which projects to actually build — which problem to pick, how to avoid the tutorial swamp — I covered that in detail in how personal projects help you land a job. Here the focus is what to do with the projects once they exist.
A live link beats a repository
If the project runs, put it online. A public deploy — Vercel, Netlify, Cloudflare Pages, Fly, any of them — changes the nature of what you are showing. A repository is a promise: "trust that this works". A live link is proof: click and use it.
Most technical recruiters will not clone your repo, install dependencies, and spin up a local server just to see your CRUD working. They will click the link, or they will see nothing. Pure backend with no interface still deserves a deploy: stand the API up, leave an example endpoint responding, document one curl call. The friction between "I want to see it" and "I am seeing it" needs to be zero.
The README is the project's first impression
Here lives the most common and cheapest mistake to fix. A project without a decent README is a project nobody understands — and a good README is literally half the impression the code makes. If someone opens the repo and sees a wall of files without a single line explaining what it is, the perfect code underneath does not save it.
A README worth its salt opens with the problem: what it solves, for whom. Then it shows how to run it in a few steps. And then — the part that separates junior from mid-level in the eyes of the reader — it explains the decisions. Why Postgres and not Mongo. Why you skipped a state framework. What you would swap if you had more time. Those tradeoffs reveal that you think like an engineer, not just type like one. If writing from scratch stalls you, a README generator takes the blank page out of the way and lets you focus on the content that matters.
Show decisions, not just code
Any LLM generates code today. What sets you apart is the reasoning behind it. That is why the strongest portfolio does not display files — it displays choices. A short "how I thought about it" section on each project, or a clean commit history where you can follow the evolution, is worth more than a thousand perfect lines without context.
Be careful with the commit history, by the way. A technical recruiter opens the commits tab. A sequence of "fix", "fix2", "asdf", "final final now it works" tells a bad story. You do not need to be religious about conventional commits, but messages that describe what changed and why signal discipline. And discipline is hirable.
What to cut without mercy
Some things age the portfolio instantly. The percentage skill bars — "JavaScript 85%, Python 70%" — mean nothing and everyone knows it. Eighty-five percent measured against what? Cut them. The "passionate about technology since I was 12" paragraph adds nothing either; swap it for one concrete sentence about what you do and where you want to go.
Dead links are the worst of all: a "live" project that returns a 404 proves exactly the incompetence you are trying to hide. Test every link before sending the portfolio to any role. Carousels of technology logos without context, certificates from forty-minute courses, blurry screenshots — all of that takes up space that could be working in your favor.
Tailor it to the role
A portfolio does not have to be static or single. If you are applying for a frontend role, the project with the most polished interface goes first. If it is backend, lead with the well-modeled API and the README that explains the architecture. Reordering the projects to fit the role takes five minutes and changes the entire first impression.
The minimum viable portfolio: two to four real projects, the GitHub with clean commits, a short and honest about, a clear way to make contact. A technical blog is a bonus — it shows you communicate — but only if you will actually keep it up. A blog with one post from 2023 is worse than no blog at all.
Frequently asked questions
How many projects should I have in my portfolio?
Two to four substantial projects is the sweet spot. Above that you dilute attention and risk including weak work that drags the average down. Prefer depth: one project you explain well is worth more than five that merely exist.
Do I need the projects deployed, or is GitHub enough?
Deploy whenever possible. The live link removes friction and proves it works; the recruiter rarely clones the repo. For backend projects, stand the API up with an example endpoint and document a call in the README.
Is a blog worth having in a portfolio?
It is worth it if you will maintain it. An active blog shows you can communicate technical ideas, which is rare and valuable. But a blog with a single old post reads as an abandoned project — in that case, better not to have one.
Should I list technologies I used only once?
List what you can defend in an interview. Padding the stack with things you touched for an afternoon only creates expectations the technical conversation will unmask. Honesty here protects you.
Takeaway
A portfolio is not an inventory of what you have seen; it is an argument about what you deliver. One finished, deployed project with a README that explains the problem and the decisions knocks out ten tutorial clones without breaking a sweat. Cut the percentage bars, kill the broken links, clean the commit history, and make the value obvious in the first twenty seconds. The reader is in a hurry — make their life easy and they will make yours easy.
- 01 Does the PageSpeed Score Affect SEO? 100/100 and Failing Google doesn't rank on PageSpeed's 0 to 100 score but on Core Web Vitals from real users. Here's why a site scores 100/100 and still fails in the field.
- 02 Unit test vs integration test: the difference in practice The difference between unit and integration tests with API and database examples: what each one catches, what it costs, and when to use each in your project.