How to Make a Developer Portfolio

What a portfolio is actually for

You are asking someone to believe you can do a job before anyone has paid you to do it. Employment history is the shortcut most candidates use to make that believable. Without one, you have to supply the evidence directly.

That is the whole purpose, and it explains most of the specific advice below. A reviewer opening your portfolio is answering three questions in about ninety seconds: can this person build things, can they finish them, and can they explain what they built? Everything that helps answer those belongs. Everything else is decoration.

It also explains the most common failure. Most students who ask us for help can code perfectly well. The gap is that their ability is not legible — it is sitting in undocumented repositories with names like assignment3, none of which are deployed. That is a documentation and positioning problem, not a programming one, and it is much faster to fix.

What a developer portfolio should contain

Five layers, each doing one job:

1. The claim — Say what you build and what you want. One sentence at the top: role, technologies, what you are looking for. Everything below it is evidence for this claim.
2. The evidence — Two or three projects a reviewer can verify. A live link or a recording, the stack named, and one technical decision explained with its alternative.
3. The source — A GitHub profile that supports the evidence. The same projects pinned, documented and running. This is where a technical reviewer goes to check you are telling the truth.
4. The summary — A one-page CV that links back to all of it. The compressed version, written to survive a 20-second scan and get you to the point where someone opens the rest.
5. The consistency — A LinkedIn profile that says the same thing. Reviewers cross-reference. Three profiles telling three different stories is the most common own goal on this list.

Notice what is not on that list: a blog, a timeline, testimonials, a skills chart, a hero animation, a custom cursor. None of those are forbidden. None of them substitute for the five above, and all of them are things people build instead of the five above.

Step 1 — Audit what you already have

Start here rather than by building something new. Most people are closer than they think and are missing presentation rather than substance.

Open your GitHub, your CV and any site you have, and write down honestly:

• Every project you could conceivably show, and whether it is finished
• Which of them are deployed at a URL someone could open
• Which have a README that explains the project rather than the install steps
• What your GitHub profile shows to a stranger right now
• Whether your CV, LinkedIn and site say the same thing

The section with the most gaps is what you fix first — not the one you most enjoy working on. For most students that turns out to be documentation.

Step 2 — Pick a target role

Front-end, back-end, full-stack, mobile, data. Pick one to lead with, even if you are not certain.

A portfolio aimed at front-end roles that turns out to be the wrong choice is far more effective than a portfolio aimed at nothing. Being unspecific reads as being unsure, and it makes every subsequent decision harder: which projects to feature, which technologies to emphasise, what to say in your header.

The counter-intuitive part is that narrowing increases your response rate. “I build back-end services in Python and Go” is a claim someone can evaluate against a role. “Full-Stack | Mobile | AI/ML | Cloud” reads as someone who has done a lot of tutorials.

Step 3 — Choose two or three projects

Not eight. Reviewers look at your first two projects and form a view; the third gets skimmed and the rest are functionally invisible.

The shape that works:

• One substantial project that took weeks and has a genuinely hard part
• One that shows a different dimension — if the first is back-end, make this one user-facing
• Optionally one small polished thing — a CLI tool published to a package registry, a browser extension in a store

Score your candidates on four things:

If a project scores badly on realistic scope, cut features rather than dropping the project. Thirty specified briefs are in the portfolio project ideas guide if you need somewhere to start.

Step 4 — Upgrade and deploy what you have

You probably do not need to build from scratch. An assignment becomes portfolio evidence when you add the things marking schemes ignore, and that is about two evenings against three weeks for something new.

The five changes, in order of return:

1. Deploy it. Free hosting covers almost every stack — Vercel, Netlify and Cloudflare Pages for front-end and full-stack, Railway, Render and Fly.io for anything with a server, GitHub Pages for static sites. A clickable URL is the single highest-value addition available to you.
2. Add one feature nobody asked for. A search, an export, an API in front of a console app. The signal is that you kept going after the mark was in.
3. Add a handful of tests. Five meaningful ones beat a coverage badge. Test the thing that would actually break.
4. Handle the cases the sample data never triggered. Empty state, malformed input, the external API being down. The application should not crash with a stack trace on screen.
5. Rename it something readable. library-lending-system, not cs2043-assignment-3. GitHub redirects the old URL.

If a project genuinely cannot be deployed — a mobile app, a game, a CLI tool — record a 30-second screen capture instead. Never make a reviewer imagine it working.

Step 5 — Document them properly

An undocumented project cannot be assessed, so it counts for nothing. This is where most portfolios are actually lost.

A README should answer a reviewer’s questions in the order they occur: what is this, can I see it working, what is it built with, how does it work, can I run it, what did you learn. Most student READMEs answer only the fifth.

Two sections do a disproportionate amount of the work:

One technical decision, with the rejected alternative. “I used Postgres rather than SQLite because the scheduler and the web process both write, and SQLite’s single-writer lock was causing timeouts.” That sentence tells a reviewer you understood a constraint and made a choice you can defend.

Something that went wrong. Specific, not general. “Deployment was challenging” communicates nothing. “Times were stored without timezone information, so fixtures shifted by an hour when the clocks changed — I moved storage to UTC and added a test across a DST boundary” communicates diagnosis, root-cause thinking and regression testing in one sentence.

Do one README properly rather than eight badly. The README template is the full structure.

Step 6 — Fix your GitHub

For most junior applications this is the first thing a technical reviewer opens, and it gets judged whether or not you intend it to be part of your portfolio.

The two-hour version:

• Pin your best repositories. Ten minutes, and the highest-leverage thing on the list — otherwise GitHub shows whatever you touched last.
• Write a profile README. Create a repository named after your username, add a README.md, keep it to 150 words.
• Fill in bio, location and website. Two minutes.
• Add descriptions and topics to every public repository.
• Audit for secrets. Search for .env, api_key, password and secret across your history, not only your current files. Rotate anything you find.
• Archive the noise. Nobody is impressed by 40 repositories.

The full four-pass version is in the GitHub profile guide.

Step 7 — Build the website

Seventh, not first. Building a portfolio site before you know which projects go on it is how people lose three weekends to choosing a CSS framework.

One page, five sections, deployed: header, projects, about, skills, contact. That is enough, and it can be built in a weekend. A five-page site with three empty pages is worse than one good page.

It is not strictly mandatory. For back-end, data and systems roles a well-documented GitHub plus a good CV is genuinely sufficient. For front-end and full-stack roles the site is itself a work sample, so it carries more weight there.

Full structure and copy prompts: how to make a portfolio website.

Step 8 — Write the CV

The portfolio only gets opened if the CV survives the first filter, which takes between eight and twenty seconds.

One page. PDF, named firstname-lastname-cv.pdf. Portfolio and GitHub as clickable links in the header. Projects at the top where employment would normally go, three lines each following the pattern: verb, what, (stack), what happened.

Delete the percentage bars from your skills section. Technical reviewers dislike them consistently, and “Python — 87%” is not a claim anyone can evaluate.

The developer CV guide has the bullet patterns and a full worked example.

Step 9 — Run a final audit

Do this as a walkthrough rather than a checklist. Most portfolio failures happen at the joins: the CV links to a page that no longer exists, the featured project points at a private repository, GitHub shows a completely different set of work.

Open a private browser window and follow the route a reviewer takes — CV, LinkedIn, portfolio, best project, GitHub — writing down what breaks without fixing anything as you go.

Then get one outside opinion. Send the link to someone not on your course and ask a single question: what do you think I do? If their answer does not match the role you are applying for, the positioning is the problem, not the projects — and that is a one-evening fix worth more than another feature.

How long this takes

With some code already written, roughly two weeks of focused evenings — around 10 to 15 hours of actual work:

Starting with no projects at all, budget four to six weeks. The part that takes longest is not the code — it is writing the explanations.

The mistakes that cost the most

• Building a new project when you should be documenting an old one. The most common and most expensive error.
• Eight projects at 60%. It reads as someone who starts things.
• Nothing deployed. A repository asks the reviewer to do work. A URL does not.
• The site before the projects. Three weekends on a CSS framework.
• Percentage bars on skills. Actively disliked, and they invite a question you cannot answer.
• Presenting code you cannot explain. Including AI-assisted code. An interviewer establishes this in about ninety seconds and there is no recovery.
• Waiting until it is perfect. The portfolio you send in October gets you interviews the better one you would have had in March does not.

The bar is not perfect. It is attachable — honest, working, clearly presented. Ship it, apply, and keep improving it while you wait for replies.