Portfolio

Building a Developer Portfolio That Gets You Hired (With Examples)

You spent six months building things. You pushed code every day. You have a GitHub profile and maybe a personal site. Yet your applications keep going quiet. The problem almost certainly is not your skills — it is how your portfolio communicates those skills to the people who matter: the engineering managers, tech leads, and recruiters who have roughly four minutes to decide whether to advance you.

This guide walks through what that audience actually looks for, based on publicly available hiring discussions, engineering blog posts, and the observable patterns across successful junior-to-mid-level developer hires. By the end you will know exactly what to fix.

Why Most Portfolios Fail

Most developer portfolios fail for the same handful of reasons, none of which have anything to do with the developer's actual ability.

The "collection of stuff" problem

A portfolio that shows everything you have ever touched tells the viewer nothing about what you are actually good at. Fifteen repositories with no explanations, half of them unfinished tutorial follow-alongs, communicate noise. Hiring teams are pattern-matching machines — they need signal, fast. Curate ruthlessly: show three to five projects you can defend in depth rather than twelve you can barely describe.

Nothing works

Broken live demos are worse than no live demo at all. A 502 error on your "production" app suggests you do not own your deployments, you do not monitor your systems, and you do not care how you look to interviewers. Every project you link to should be live, functional, and stable on the day you send an application.

The portfolio itself is the only project

If the most interesting technical thing in your portfolio is the portfolio website, you have a problem. The site should be a frame for your other work, not the centrepiece. A flashy animated portfolio with nothing substantial behind it reads as style over substance.

What Engineering Managers Look at First

Based on accounts from engineering managers at mid-size and large tech companies, here is the realistic sequence in which your portfolio gets evaluated.

1. GitHub profile overview (30 seconds): Pinned repos, contribution graph, language breakdown. Is this someone who codes consistently? Do the repo descriptions make immediate sense?
2. One pinned repo, top-level README (60 seconds): What problem does this solve? Does it have a live link? Can I see the code structure?
3. Personal site, if linked (60 seconds): Does the site itself work? Is there a clear "about" + project showcase? Does it load fast?
4. Resume cross-reference (30 seconds): Do the projects mentioned on the resume match what I see on GitHub? Are the tech stack claims consistent?

Everything after those first three minutes is optional reading that only happens if you passed the initial filter. Your job is to survive that filter. Everything else — your blog posts, your Twitter/X presence, your conference talks — is a bonus that compounds over time but should not be your primary focus when you are actively job hunting.

GitHub Must-Haves

Pinned repositories

GitHub lets you pin up to six repositories. Use all six slots. Pin only complete, documented projects — not forks, not "learning-X" repos, and not whatever GitHub decided to pin by default based on your star activity. Each pinned repo should have: a clear one-line description set in the repo settings (not just in the README), the correct primary language tag, and one or two topic tags such as react, postgresql, or open-source.

README quality

Every pinned repository needs a README that covers four things in order: what the project does (one clear sentence), why it exists or what problem it solves, how to run it locally, and a link to the live version or a demo recording. Include a screenshot or animated GIF near the top — reviewers are visual and will not scroll past a wall of text to find out if the app looks decent.

A README that says "A full-stack web app built with React and Node" tells the reader nothing they could not see from the language tags. A README that says "A budget tracker that imports CSV exports from major UK banks, categorises spending with a locally-run ML model, and generates monthly PDF reports" tells them exactly what you built and why it is worth clicking into.

Commit history and message quality

Interviewers sometimes scroll through your commit history. What they are looking for is not frequency but pattern. Commits like "fix stuff", "wip", or "asdfgh" suggest you treat version control as a save button rather than a communication tool. Aim for present-tense, specific messages: "Add pagination to the transactions table", "Fix null pointer in CSV parser when header row is missing", "Refactor auth middleware to use JWT instead of sessions". This matters especially for your pinned projects.

Contribution graph

A completely empty contribution graph is a yellow flag. It does not have to be green every single day — nobody expects that — but evidence of ongoing activity over several months signals genuine engagement with the craft. If most of your work is in private repositories at a current job, pin a note in your profile README explaining that and link to any open-source contributions you have made elsewhere. Transparency is always better than an unexplained gap.

Personal Site Essentials

A personal site is not required to get hired, but it meaningfully differentiates you at the junior and early-mid level where you are competing with dozens of candidates who have similar GitHub profiles. Here is what the site must contain to be useful rather than just decorative.

Above the fold

Your name, your specialisation in plain English ("Full-stack engineer focused on React and Go backends"), and visible links to your GitHub, LinkedIn, and resume — all without scrolling. Do not make people hunt for the basics. Your headline should be a value statement rather than a job title you do not yet hold. "I build fast, accessible web apps and write the documentation to match" is more compelling than "Junior Software Developer".

Project showcase with context

For each featured project include: a screenshot or short video, a two-sentence description of the problem and the solution, the tech stack (honest — list only what you meaningfully used and can speak to), a link to the live app, and a link to the source code. Avoid stacking up technology badges without context. "Built with React, TypeScript, PostgreSQL, Docker, Redis, Kubernetes, GraphQL, and Terraform" on what is clearly a simple to-do app actively raises eyebrows.

A brief about section

Two or three sentences about who you are, what kinds of problems you enjoy working on, and what you are looking for next. Keep it professional but human — recruiters do read these, and a personality that comes through makes you easier to advocate for internally.

Performance and accessibility

Run your site through Google PageSpeed Insights before linking it on any application. A portfolio site that scores below 80 on performance or has obvious accessibility failures — missing alt text, poor colour contrast, keyboard traps — actively works against you when applying for front-end or full-stack roles. Your personal site is the one piece of software you control completely and can optimise without constraints. It should be excellent on all fronts.

What Projects to Build (and Why CRUD Apps Don't Count)

The single most common portfolio mistake is filling it with apps that demonstrate only the ability to follow a tutorial. A to-do app, a weather app, a basic blog, and a recipe search all show that you understand CRUD operations and can wire up an API. They do not show that you can identify a real problem, make architectural decisions under constraints, or handle the messiness of real-world data.

Projects that stand out

• Tools that solve a problem you actually had. A script that automatically categorises your bank statement exports and flags subscriptions you forgot about is more interesting than a notes app, because it had a real use case, real edge cases, and real data messiness to handle.
• Projects with non-trivial data. Working with real-world datasets — public transit feeds, weather APIs, government open data, sports statistics — forces you to handle inconsistencies and edge cases that tutorials never cover. That problem-solving is what interviewers want to see.
• Projects where you made and can explain architectural decisions. Did you choose a specific database for a specific reason? Did you benchmark two approaches and pick one? Did you design an API that a third party could consume? These choices are interview conversation starters.
• Open-source contributions. Even small pull requests to established projects — documentation fixes that involve understanding the codebase, bug fixes with clear reproduction steps — demonstrate you can read unfamiliar code, follow contribution guidelines, and collaborate asynchronously. A merged PR to a project with a few thousand GitHub stars is highly visible and credible signal.
• A project with measurable outcomes. "Built a scraper that reduced my freelance job search time from three hours to twenty minutes per week" is infinitely more compelling than "built a web scraper". Quantify the value wherever you honestly can.

What to do with your existing CRUD apps

Do not delete them — they show learning history and interviewers occasionally look at your full repository list. Simply unpin them from your GitHub profile and do not feature them on your personal site. If someone finds them by browsing your profile, that is fine. They just should not be the first thing a reviewer sees when evaluating whether to advance you.

How to Document a Project So It Tells a Story

Great project documentation does not just explain what you built — it explains the thinking behind your decisions. This is what separates a portfolio that demonstrates seniority of mindset from one that merely demonstrates execution ability. You can have the same technical skills as another candidate and win or lose the callback based entirely on how well your documentation tells the story of your reasoning.

Lead with the problem, not the technology

Start every README and every project description with the problem, not the stack. "I built this because I kept losing track of freelance invoices scattered across email threads and three different spreadsheets" is a problem people relate to. "A full-stack invoicing app with React and Node.js" is a tech stack list with no narrative weight. Problems resonate; tech lists do not.

Surface your key technical decisions

Pick one or two meaningful architectural or engineering decisions you made and explain your reasoning briefly. "I chose SQLite over PostgreSQL here because the app runs locally on the user's machine and I did not want to require a database server installation — for a single-user tool, SQLite's simplicity and zero-config setup were the right trade-offs" is the kind of thinking that tells an interviewer you reason like an engineer rather than a tutorial follower.

Include a "what I would do differently" note

A short section in your README titled "Known limitations" or "What I'd change" shows intellectual honesty and a growth mindset — two things engineering managers and tech leads explicitly look for. It also pre-empts and neutralises interview questions like "if you could rebuild this from scratch, what would you do differently?" You have already answered it thoughtfully in writing.

Live Demos vs Screenshots

Conventional wisdom says live demos are always better than screenshots. The reality is more nuanced. The wrong kind of live demo can actively hurt your chances.

When live demos win

A live demo wins when it works reliably, loads in under three seconds, and the core functionality is immediately obvious without instructions. If someone can land on your app and understand its purpose within thirty seconds of interacting with it, a live demo is far more compelling than any screenshot collection. This is the gold standard to aim for.

When a video walkthrough is better

If your app requires account creation with no guest or demo mode, a live demo forces the reviewer to sign up — which most will not do. Instead, include a short screen recording (Loom, OBS, or QuickTime, exported to MP4 and linked near the top of your README) walking through the core user flow in sixty to ninety seconds. This is often more impressive than a live demo because you control the narrative, you can highlight the non-obvious features, and you can show the happy path without the reviewer getting confused.

If your project is a CLI tool, a data pipeline, or anything that is not browser-based, a well-edited terminal recording using tools like Asciinema is both appropriate and genuinely impressive to technical reviewers.

Keeping demos alive

Free tiers on Vercel, Netlify, Railway, and Render are sufficient for portfolio projects. The key is to configure automatic deploys from your main branch so the live version always reflects your latest code, and to check your deployed apps monthly to catch cold-start issues or free-tier expiry events before an interviewer does. A reviewer who hits a broken demo rarely gives you a second chance.

If your app requires environment variables or API keys, document clearly in the README exactly what variables are needed to run it locally and where to obtain them — do not assume reviewers will reverse-engineer your setup. And never hardcode credentials anywhere in a portfolio project, even temporarily. Interviewers do look at your actual code, and a committed API key sends a strong negative signal about your security instincts.