Developer Portfolio: What Hiring Managers Actually Look For

There is a gap between how developers build portfolios and how they are read. Developers build them like a technical showcase — architecture diagrams, technology lists, a dark theme with a terminal animation. They are read like a risk assessment: if I put this person in front of our codebase and our deadlines, does that go well?

Nobody reads your portfolio to admire it. They read it to reduce uncertainty about you, quickly, so they can either move you forward or move on to the next tab. Once you accept that, most portfolio decisions get easier.

This piece covers what actually gets checked, in what order, and what to do about each. It applies whether you are freelancing, contracting, or applying for a salaried role — the reader is doing the same risk assessment either way.

The thirty-second pass

Almost every portfolio review starts with a fast triage. The reader is not evaluating your work yet; they are deciding whether it is worth evaluating. Four questions get asked, roughly in this order.

Four questions, asked in this order. Answer them out of order and you lose the reader.

0–5 seconds: can I tell what you do?

The reader wants a category and a specialism. "Full-stack developer" is a category with no specialism, which means it survives triage but tells them nothing. "Back-end developer — payments and billing systems, mostly Go and Postgres" gives them somewhere to file you.

Specialising feels like it narrows your opportunities. In practice it does the opposite: generalist positioning makes you the compromise candidate for everything and the obvious candidate for nothing. The developers who get inbound work are almost always the ones with a legible specialism, even when they can do far more than it implies.

5–12 seconds: is any of this real?

The reader is scanning your project list for signals of reality — a live URL, a real product name, users, a company. Tutorial-shaped projects are recognised instantly and they are costly, because they say you have practised but not shipped.

The fastest fix is not building something more impressive. It is making the real things you have already done look real: a link that works, a screenshot of the actual interface rather than a mockup, and a sentence that mentions consequences.

12–22 seconds: have you done work like mine?

This is the relevance check, and it is why ordering matters more than most developers think. The reader will not dig for the project that matches their problem — they will assume the first two are your best and judge from those.

If you are chasing a specific kind of work, the project closest to that work goes first, even if it is not the one you are proudest of. Reorder your portfolio when you change what you are chasing.

22–30 seconds: is there a person here?

A name, a face, a location or timezone, and a working way to make contact. Anonymous portfolios read as either unfinished or evasive. If someone has decided in twenty-five seconds that they want to talk to you, the last five seconds should not be spent hunting for how.

Which projects earn their place

The usual advice is "quality over quantity", which is true and useless without a filter. Here is a more decidable one. Two axes: did you make the decisions, and did it ship?

Difficulty is not the axis. Ownership and shipping are.

Original and shipped, or client work that shipped — lead with these. Real constraints leave fingerprints all over a project, and experienced reviewers can see them.

Original but unshipped — keep at most one, and only if the thinking is visible. An unfinished project with a genuinely interesting design decision written up can outperform a finished CRUD app.

Tutorial follow-alongs — remove them. Not because learning from tutorials is bad, but because a portfolio is a claim about your judgement, and in a tutorial every judgement call was made by someone else. A reviewer who has seen the same to-do app forty times will discount everything around it.

Three to five entries is the right range. If removing your weakest project leaves you with two, that is still better than four with a filler.

The README is part of the portfolio

If your project links go to GitHub, the README is not documentation — it is the case study, and for many reviewers it is the only long-form writing of yours they will ever read.

A README that gets you hired opens with what the project does and who for, in two sentences, above the fold. Then a screenshot or a short recording, because a reviewer will not clone your repository to find out what it looks like. Then a section that most READMEs skip entirely: the decisions. Why this database. Why you did not use the obvious framework. What you would do differently at ten times the traffic.

That last section is the one that changes minds. It is the difference between "this person can assemble software" and "this person can be trusted with a decision when I am not in the room".

What to write on a project card

Most project descriptions are technology lists. A technology list tells a reader what you touched, not what you did. A card that does its job has four parts:

• What it is, in plain language. "A scheduling tool for physiotherapy clinics", not "a full-stack CRUD application".
• Your role, honestly scoped. "Sole developer", "led the front end, three-person team", "inherited and rewrote the sync layer". Ambiguity here is the fastest way to lose trust in an interview.
• One decision or constraint. "Had to work offline in clinics with unreliable wifi, so writes queue locally and reconcile on reconnect." This single sentence does more than a paragraph of stack description.
• An outcome. Users, load times, error rates, hours saved, a client quote. If you have no numbers, describe what changed.

Keep the stack list — it is genuinely useful for keyword matching and for reviewers filtering on a specific technology. Just stop letting it be the whole description.

The GitHub question

Two things are worth separating: whether your GitHub profile is a portfolio, and whether it should be linked from one.

It is not a portfolio. A repository list is unordered, unexplained, and full of forks and experiments that misrepresent you. Sending a client to your GitHub profile makes them do the work of figuring out which of thirty repositories is the good one.

It should absolutely be linked. Reviewers do click through, and what they look for is narrower than developers fear: does the code look maintainable, are commit messages coherent, is there any evidence of tests. They are not counting your contribution squares. The green-graph anxiety is largely self-inflicted; a sparse graph with three well-built repositories reads better than a dense one with none.

What is worth doing: pin your best four repositories, give each a real description, and make sure their READMEs meet the bar above.

Live demos, and what to do when you cannot host one

A working link is the strongest single element on a project card, because it converts a claim into a verifiable fact in one click. Host what you can — a static front end costs nothing to deploy, and a small back end usually fits inside a free tier.

When you genuinely cannot — the project is a client's private system, it needs credentials, or it costs real money to run — do not leave the reader with nothing. In order of preference:

1. A short screen recording. Forty seconds of the actual thing working, no narration required. This is almost as good as a live link and often easier to arrange.
2. A demo account. A sandbox login with seeded data, clearly labelled.
3. Annotated screenshots. Real interface, with a line of text explaining what each screen does.

What does not work is a link to a dead deployment. A 404 on your own portfolio is worse than no link at all, because it suggests you have not looked at your own site in a year. Check every link before you send it anywhere.

Things that quietly disqualify you

These rarely get mentioned in feedback, because the reader has already moved on.

• A slow portfolio from someone selling performance work. The site is a work sample whether you intended it or not. Google's Core Web Vitals thresholds — 2.5 seconds to largest paint, 200 milliseconds to interaction response, 0.1 layout shift — are a reasonable bar for a page that is mostly text and images.
• A broken mobile layout on a front-end portfolio. Self-explanatory, and extremely common.
• Overclaiming your role. "Built" when you mean "contributed to" survives the portfolio and dies in the interview, along with everything else you said.
• An abandoned blog. Three posts from two years ago is worse than no blog. Remove the section or write something.
• Copy that could describe anyone. "Passionate developer who loves clean code" appears on thousands of portfolios. It is not wrong, it is invisible.

If you have no professional experience yet

The advice above assumes shipped work. If you do not have any, the goal is to manufacture the closest honest equivalent — which is not a bigger tutorial project.

Build something small for a real user. A local business, a community group, a friend with a spreadsheet problem, an open-source project with an open issue. The specific advantage is not the code; it is that a real user generates real constraints, real feedback and a real outcome, which is exactly the raw material a portfolio needs and a solo project cannot fabricate.

Then write it up properly. A single well-documented project with a genuine user, a stated constraint and an honest reflection will outperform five polished clones, because it is evidence of the thing employers are actually screening for: that you can operate when the requirements are messy.

Contributing to open source works for the same reason — your code was reviewed by someone with standards, and that review is public.

The About section developers skip

Developers write project descriptions carefully and About sections in four minutes at the end. It is the wrong allocation, because by the time someone reaches your About section they have already accepted that you can do the work — this section decides whether they want to work with you specifically.

Three things belong in it, and almost nothing else.

How you got here, in two sentences. Bootcamp, computer science degree, self-taught while doing something else — all of these are fine, and being straightforward about it is better than the vague "several years in the industry" that makes readers assume you are hiding a gap. If you came from another field, say so: a developer who spent six years in logistics before switching has domain knowledge that is genuinely scarce.

What you are good at that is slightly unusual. Not your stack — the thing underneath it. "I'm the person who ends up owning the flaky test suite", "I like the part of a project where the requirements are still unclear", "I've done enough on-call to design for the 3am version of a system." These sentences are memorable because they could not have been written by a generator, and they tell a hiring manager something they cannot get from a CV.

How you work with other people. Freelance and contract work in particular is bought partly on this. Do you prefer async, do you want access to the client's users, do you write things down. Stating it filters out the engagements that would have gone badly anyway.

What does not belong: a list of technologies already on your project cards, "passionate about clean code", and hobbies that have nothing to do with anything. One line of personality is charming; a paragraph of it reads as filler.

Contract and freelance developer portfolios: what changes

The advice above holds whether you are job-hunting or freelancing, with three adjustments if clients are paying you directly.

• Add what someone can buy. An employer is hiring a person; a client is buying an engagement. Say what the engagements look like — "two-week performance audits", "front-end build on a fixed scope", "ongoing retained support" — and roughly what they cost or how long they take. Ambiguity here produces enquiries that were never going to convert.
• Be explicit about availability and timezone. A client deciding between three developers will discount the one whose availability is a mystery. "Currently booking from March, based in Lisbon, overlap with US Eastern until 1pm ET" removes an entire round of email.
• Show business outcomes, not just technical ones. "Reduced bundle size by 40%" is a technical result. "Reduced bundle size by 40%, which cut mobile bounce rate by a third" is the version a client can evaluate. Where you have both, lead with the one the buyer cares about.

A twenty-minute audit

Open your portfolio on a phone, ideally one that is not the newest model, and work through this in order. Every item is a yes or a no.

1. Within five seconds of loading, can a stranger say what kind of developer you are and who you build for?
2. Is your specialism in the page title, not just the page body?
3. Are there between three and five projects, with the most relevant one first?
4. Does every project link work? Click all of them.
5. Does every project card state your role unambiguously?
6. Does at least one project describe a decision or a constraint, not just a stack?
7. Does at least one project state an outcome?
8. Do your pinned GitHub repositories have real descriptions and readable READMEs?
9. Is there a name, a face and a location or timezone?
10. Is there exactly one obvious way to contact you, and does it work when you are logged out?
11. Does the page load in under three seconds on mobile data?
12. Is there anything on the page dated more than eighteen months ago that implies you have stopped?

Most portfolios fail four or five of these, and nearly all of the failures are twenty-minute fixes rather than rebuilds. If you are failing more than eight, the problem is structural and the eight-section structure is a faster route than patching.

Frequently asked questions

Do developers still need a portfolio site, or is GitHub enough?

You need somewhere that frames the work. GitHub stores it; a portfolio explains it, orders it, and puts your positioning in front of it. The portfolio is also the thing that ranks when someone searches your name.

How many projects should a developer portfolio have?

Three to five, ordered so the most relevant is first. More than five and the reader stops treating the list as curated.

Should I include my résumé?

Link to a PDF, yes. Recruiters and internal hiring processes still want one, and making them ask for it adds friction at exactly the wrong moment. If you do not have a current one, our résumé builder will produce a plain PDF free — it carries one small "Created with Bunfolio" line at the foot of the page, which is better known before you export than after.

Does the technology I use to build the portfolio matter?

Far less than developers assume. Reviewers notice whether it is fast, readable and works on a phone. Nobody has ever been rejected for building their portfolio with a ready-made developer portfolio template instead of hand-rolling it — and the hours saved are better spent on the case study.

Should I show side projects that failed?

Yes, if you can articulate why they failed. A project with an honest post-mortem demonstrates judgement, which is rarer and more valuable than a project that merely worked.

How often should I update it?

Reorder whenever you change what you are looking for, and refresh content quarterly. The most common failure is not a bad portfolio — it is a good portfolio describing the job you had two roles ago.

---

How we put this guide together

Bunfolio builds portfolio sites, which means we spend a lot of time looking at what developers actually publish and where those pages fall short. The structure above reflects that, and the technical thresholds are cited to primary sources — the Core Web Vitals figures come from web.dev, not from a secondary summary.

We have avoided quoting the widely circulated statistics about what percentage of hiring managers prefer portfolios to résumés. Those numbers appear in a lot of articles and trace back to no identifiable study, and citing them would weaken the guide rather than strengthen it. Where we make a claim about what reviewers do, it is presented as our judgement, and you should weigh it as such.

Related reading: how to write a portfolio case study and how to build a freelance portfolio website that wins clients.