As a graduate, I was told I needed a portfolio to stand out in a tough market. After years of lecturers telling me what to do, I was utterly lost. What did I build, and how did I share it? My coding assignments were uploaded as zip files, my degree didn't teach GitHub.

Years later, stalling at mid-level, I still had the same problem. I could write code someone else defined, but didn't know what I was supposed to build for a portfolio. I didn't know what direction I was going, I didn't know what my portfolio needed to prove.

It's only now that I have a clearer idea of what sort of engineer I want to be, the direction I want to go, that the portfolio question has finally clicked. Not because I've come up with an incredible project idea, but because I understand now what I'm trying to show, and to who.

That's the piece most advice skips. It'll give you a list of things to build, rather than showing you how to figure out what your portfolio needs.

This isn't a list of project ideas. It's the thinking I wish I'd had a decade ago.

What Is the Portfolio For?

Most portfolio advice fails to ask the most important question, why are you building a portfolio? “Because someone more senior said I needed to” isn't enough. Spending some time thinking about what you're trying to demonstrate and to whom will guide you towards what you should be building.

Coding vs Engineering

Early on in your career you probably just want to demonstrate that you can write code outside of a tutorial or course assignment. A simple, complete, functional project will do the job. Later on you need to demonstrate that you can think beyond the ticket, that you can decompose a problem into actionable tasks. That's something a bit harder to demonstrate entirely with code, but including architecture decisions in your README explaining the why as well as the what, can give a hint of how you think.

Who Is It For?

Recruiters may only spend a couple of minutes on your portfolio, looking for keywords that match their job spec. Talent acquisition could be looking for a hint of the engineer you could become. The hiring manager might be looking at immediate technical aptitude in their stack. An interviewer could ask you to walk through your project, challenge your decisions, and ask what you would improve. Your fellow engineers may be looking for a solution that comes from someone who has faced the same problem.

Format Is Also a Demonstration

Some still repeated advice is to build a portfolio website. If you're a backend engineer, what does this prove? That you can fumble your way through an unfamiliar domain, wasting time on polishing UI rather than demonstrating the skills you already have?

A well-organised GitHub profile - pinned repos, a proper profile README, project READMEs that explain your thinking rather than just your stack - demonstrates the same narrative a bespoke site is supposed to. For a while my blog was solely my portfolio, because it's a much easier medium to demonstrate senior engineering instincts than pure code. Perhaps you create YouTube coding tutorials, or an engineering podcast - link that instead.

What to Demonstrate by Level

Not every company uses the same titles or progression. There's no shared definition of what makes a junior/mid/senior engineer, and titles may vary depending on organisation. Take these categories with a pinch of salt.

Graduate/Junior

At this stage, there's not a lot to prove - only that you can write code without someone dictating the solution for you. This is where a lot of portfolio advice falls down. There are plenty of examples of TODO list apps, solutions to coding katas in a variety of languages, and AI can throw together something workable without much effort. That's not to say you need to create something entirely new, build a simple version of something you're familiar with using, create from scratch something you use a package for, put a new spin on the old favourites - like adding gamification to your TODO list.

The key here is to demonstrate that you can write working code for an unfamiliar problem. Try to avoid third party packages unless proficiency with those is what you want to demonstrate. Same goes for code generation tools and AI. Do it by hand and be prepared to explain what every piece of code does. It's ok if it isn't perfect, no one is expecting perfect, you just need to show that you're trying.

Mid-level

At this stage, it becomes less about the code, and more about how you got there. Can you break down a vague task into something actionable? Clean, decoupled code demonstrates this up to a point, this is where documentation does the heavy lifting. Explain your architecture decisions, the trade-offs you considered, how you structured the project, and why.

Asking questions and challenging assumptions, thinking rather than just doing is an expectation at this level. It's something else that documentation demonstrates better than code. If you've chosen a non-standard solution, explain your reasoning rather than leaving the reader assuming you don't know any better. If you're building for future scalability, flag it so the reader doesn't assume you've overengineered the solution (something AI is prone to do).

Senior

At this point, the focus is on the engineering rather than the code. Instead of “can you build a thing”, it becomes “can you build a thing that outlasts you”.

Deployment and containerisation start to matter here, rather than working inside an existing CI/CD process, you're expected to build and maintain it. Hosting a working project demonstrates that you don't fall into the “works on my machine” trap.

Architecture decisions become bigger and focused on sustainability, problems are larger and more ambiguous. Documenting these is crucial, as these decisions can't be explained by code alone.

Now What?

None of this tells you what to build. That's deliberate. Knowing what you're trying to prove, and to whom is the real work. Most portfolio advice skips straight to the project idea because the project is the visible part, and frankly, the more fun part. But a technically impressive project built for the wrong audience, proving the wrong thing, is still a wasted weekend.

Once you know what you're aiming at, knowing what to build, and how to build it becomes a bit less daunting. We're not finished yet though, next time I'll dive into the practical advice for figuring that part out.