Engineering

The Engineering Portfolio: Show the Engineering, Not Just the Code

By Dan Kovac · 10 min read

An engineering portfolio is where you explain the decisions behind your code: the trade-offs you weighed, the alternatives you rejected, the things that broke, and what your work actually changed. GitHub shows what you shipped. A portfolio shows how you think. In a market where most applications are filtered by machines before a human reads them, that written record of your judgement is the part worth publishing.

That's the whole game. Everything below is detail.

Do software engineers need a portfolio if they have GitHub?

Yes, because GitHub answers the wrong question. A repo proves you can write code. It says almost nothing about whether you can engineer.

Think about what a hiring manager actually wants to know. Not "can this person write a for loop" but: can they make a sensible call under constraints? Do they understand why they chose Postgres over DynamoDB for this workload? When their design failed under load, what did they do? None of that lives in a repo. It lives in the story around the repo, and GitHub has nowhere to put it.

A README gets you partway, but READMEs are written for users of the code, not evaluators of the engineer. They tell you how to install the thing. They don't tell you that the first architecture used polling, fell over at 10,000 events a minute, and got rewritten around a queue after a painful week of debugging. That's the interesting part. That's the engineering.

There's also a colder reason: nobody reads your commits. A recruiter or hiring manager doing a quick pass on you will read prose, not diffs. If the only artefact you have is code, you're asking a time-poor stranger to reverse-engineer your judgement from source files. Almost none of them will.

So the honest answer: GitHub is necessary but not sufficient. Keep it. Link to it. Then build the layer that explains it.

Why this matters more than it did five years ago

The market changed shape, and it's worth being clear-eyed about how.

Software engineer job postings are down roughly 49% since early 2020, and only 19% of tech job titles have posting volumes above pre-pandemic levels (Indeed Hiring Lab, which measures posting demand rather than headcount). Fewer openings means more applicants per opening, which means more filtering before a human gets involved. Survey data from Greenhouse points the same way: a majority of job seekers report having sat an AI-led interview, and most hiring managers say AI now helps them decide with fewer recruiters in the loop. Treat those as directional, ATS-vendor figures, but the direction is unambiguous. The funnel got machine-filtered.

It's hit juniors hardest. Employment of developers aged 22 to 25 fell around 20% between late 2022 and September 2025, while older cohorts held steady (Stanford Digital Economy Lab, ADP data). Entry-level is the clearest casualty: the rungs that used to absorb new grads are the ones AI tooling replaced first.

Against that backdrop, cold applying is a thin bet. Data from Ashby covering 38 million applications shows referred candidates convert from application to interview at roughly 40%, against about 3% for cold applications. Referrals are pre-vetted, so some of that gap is selection bias, not magic. You can't manufacture referrals on demand, but you can invest in the thing that makes people refer you and recruiters reach out: being findable, with evidence of your thinking already written down.

One caveat, stated plainly: a portfolio doesn't fix a hard market. Nothing does. What it changes is your odds. When someone searches your name, or a colleague wants to vouch for you, or a hiring manager is deciding between two similar CVs, a page of well-written engineering decisions is the difference between being a name and being a known quantity. That is the edge: your judgement is legible where a competitor's is still invisible.

What does an engineering portfolio have that GitHub doesn't?

Three things, and they're all writing.

Project write-ups. Two to five projects, each with a prose account of the problem, the constraints, the decisions, and the outcome. This is the core of the portfolio and the subject of the next section. Each write-up links to the repo where one exists, so the code backs the story.

A career timeline. Where you've worked, what you owned, what changed because you were there. Not a pasted CV. A short, readable narrative of your arc, with the through-line visible: the systems you've grown into, the scale you've handled, the kind of problems you keep getting handed.

Technical writing. A handful of posts on things you've actually worked through: a debugging story, a migration post-mortem, an honest comparison of two tools you've used in anger. This is the part that compounds. Every post is another page that can surface when someone searches the problem you solved, and another proof point that you can explain complex things clearly, which is half the job at senior levels.

The value isn't in any one artefact. It's in the connections between them: a write-up wired to the repo that backs it, wired to the timeline entry that shows where it happened, wired to the post where you explained the hard part. That network is what a reader reads as judgement. None of it requires a personal brand or a content strategy. It requires writing down what you already know, in a place you control, under your own name.

How do you write a project write-up?

Open with the outcome, then walk the reader through the decisions. The structure that works:

Project write-up template

1. What you built: two sentences. The problem and the shape of the solution.
2. Constraints: what boxed you in. Team size, deadline, legacy systems, budget, traffic patterns.
3. Decisions and rejected alternatives: the choices that mattered, and crucially, what you considered and turned down. "We chose SQS over Kafka because we needed exactly-once semantics less than we needed zero ops burden" says more about you than any feature list.
4. What broke: the failure, the debugging, the fix. This is where credibility lives. A write-up with no failures reads as fiction.
5. Impact: what changed. Latency numbers, cost reduction, incidents prevented, time saved. Ranges and honest estimates are fine; invented precision is not.

A concrete example of the difference. A repo README says: "A rate limiter for internal APIs, built with Redis and Lua." A portfolio write-up says: "Our payment API kept getting hammered by a batch job upstream. I built a sliding-window rate limiter in Redis with Lua scripts for atomicity. I considered a token bucket per client but rejected it because our traffic was bursty by design and we'd have punished legitimate spikes. First version had a race condition under concurrent windows that took two days to isolate. After shipping, 5xx errors on the payment path dropped from a few hundred a week to near zero."

Same project. One is a label. The other is evidence.

Keep each write-up between 400 and 800 words. Long enough to show depth, short enough that a hiring manager reads the whole thing between meetings. The same skeleton works outside engineering too; if you want a language-agnostic version, the case study template covers the structure in more detail.

What if you're a junior with no production war stories?

Write up side projects properly. A junior with three thorough write-ups of self-built projects beats a junior with a year of green squares, because the write-ups demonstrate the thing employers can't screen for at entry level: judgement.

The trap juniors fall into is treating side projects as volume. Twelve half-finished repos, each a tutorial with the variable names changed. Flip it. Build fewer things, take them further, and document the decisions as if they were production. Your to-do app becomes interesting the moment you write: "I started with local storage, hit sync conflicts when I added multi-device support, and ended up implementing a last-write-wins CRDT because full operational transforms were overkill for two devices."

You made a trade-off. You rejected an alternative for a stated reason. You hit a real problem and solved it. That's a war story. It didn't need production traffic to count; it needed you to push past the tutorial boundary and then write down what happened.

Given the numbers above for developers aged 22 to 25, this isn't optional polish for juniors. It's the most controllable lever you have. You can't create job openings. You can create evidence.

The habit: one write-up a month

A portfolio built in a panic the week you're job hunting reads like it was built in a panic. The version that works is a practice, not a project: one write-up a month, roughly an hour, while the details are fresh.

Shipped something at work? Write up the decision you'd defend in an interview anyway. Spent a weekend on a side project? Capture the trade-offs before you forget them. Debugged something gnarly? That's a post. The point of monthly cadence is that you're always writing about last month, when you still remember why you did what you did. Try to reconstruct a project from eighteen months ago and you'll get the what but lose the why, and the why is the entire value.

Twelve months of this and you have a body of work that no last-minute scramble can fake. It's also the cheapest interview prep that exists: you've already written the answers to "tell me about a technical decision you made" in your own words, on your own site. For a full checklist of what goes on the site itself, see what to include in a portfolio.

FAQ

Do software engineers really need a portfolio if they have an active GitHub?

Yes. GitHub shows code; it doesn't show reasoning, trade-offs, or impact, and almost no evaluator reads source files to infer them. A portfolio is the prose layer that explains your judgement. Keep GitHub as the evidence and the portfolio as the argument.

Do side projects count in an engineering portfolio?

They count when they're written up properly. A side project with documented constraints, rejected alternatives, and a real failure you debugged demonstrates the same judgement as production work at smaller scale. A side project that's a renamed tutorial doesn't count anywhere.

What should an engineering portfolio include?

Two to five project write-ups (each covering constraints, decisions, what broke, and impact), a career timeline with outcomes rather than duties, links to your GitHub, and ideally a few pieces of technical writing. Depth beats breadth: three thorough write-ups outperform ten shallow ones.

How do junior engineers compete in this market?

By producing evidence of judgement, since experience is the one thing they can't show. Employment of developers aged 22 to 25 fell around 20% between late 2022 and late 2025 (Stanford Digital Economy Lab, ADP), so the bar for standing out rose. Well-documented side projects, written up like production post-mortems, are the most controllable lever a junior has.

Should engineers blog?

If you can write one honest technical post a month, yes. Debugging stories, migration post-mortems, and tool comparisons from real use all compound: each one is a searchable page under your name and a demonstration that you can explain hard things clearly. Skip it if you'd only produce generic content, which helps nobody.

Will a portfolio get me interviews?

No guarantee, and be suspicious of anyone who promises one. What it does is change your odds: referred and known candidates convert to interviews at dramatically higher rates than cold applicants (Ashby, with the usual selection-bias caveat), and a portfolio is what makes you knowable to people beyond your existing network.

If you'd rather spend your hour a month writing the case study than fighting a site builder, Flexfolio's engineer pages put your projects, timeline, and writing on one domain and wire them to each other, live in minutes. The connections are the point. The writing is the work. The platform should just hold it.