How I Write Portfolio Case Studies That Don't Sound Like Marketing

I used to write portfolio entries like product landing pages. Big screenshots, feature lists, and phrases like "robust architecture." When I reread them a few months later, I could not tell what I had actually solved.

A recruiter scanning keywords might have been fooled. A senior engineer reviewing my code would not have been. This post is the case-study template I use now.

The basic rule

If I cannot link to the code that proves it, I do not write it.

That turns this:

"Optimized database queries."

Into this:

"Reduced query time from 500ms to 20ms by adding a composite index on (user_id, status) — see commit 8a4f2b."

The second one is longer, but it is the only one that survives an interview.

Project layout checkpoint illustration for this section.

Four sections I stick to

1. Context and constraint

Bad context: "I built a to-do app to learn React."

Better context: "I needed to render 10,000 data points without dropping below 60fps on a low-end Android phone."

The constraint is what makes the case study interesting. Without it, the project is just another demo.

2. Stack decision

For each major tool, I write one sentence about the trade-off that led to it.

Tool	Alternative	Why I picked it
Next.js	Create React App	Needed SSR for initial page load and SEO
Supabase	Firebase	Data was relational; joins were non-negotiable
Tailwind	Styled Components	Build-time CSS kept the bundle smaller

This table shows I understand the ecosystem, not just the syntax.

3. The moment it broke

Every case study needs one real problem. A project that went perfectly teaches nothing.

Example from a recent project:

"Updating a single chat message caused the entire chat window to re-render, which created input lag. I split the message list state from the input state using a context provider pattern. Render cycles dropped by about 90%."

That is the part people actually read.

4. Proof links

I do not just link to the repo root. I link to the specific file and line. GitHub lets you press y on a file view to get a permalink to a commit hash. I use those.

Claim: "Implemented optimistic UI updates."
Proof: src/context/ChatProvider.tsx line 45.
Claim: "Secured API endpoints with middleware."
Proof: src/middleware.ts line 12.

Specific links turn claims into evidence.

A template I copy each time

# Project Name
**Live demo:** [URL]
**Source code:** [URL]

## Goal
One sentence about the user problem or business value.
*Constraint:* What made this hard? Time, cost, performance, data?

## Technical decisions
- **Database:** Postgres. *Why?* Strict schema for financial data.
- **Hosting:** Vercel. *Why?* Edge functions were cheaper than Lambda at this scale.

## The hardest challenge: [name]
Describe the bug or bottleneck.
**Solution:** How you fixed it.
**Code reference:** Permalink to the commit or function.

## Retrospective
What would you do differently? (e.g., "I would swap Redux for TanStack Query.")

Why the retrospective matters

Junior engineers try to hide mistakes. Senior engineers point them out and explain what they learned.

Saying "I should have used SQL instead of MongoDB here; the data was too relational" is more credible than pretending the project was perfect.

Portfolio structure checkpoint illustration for this section.

Closing

A portfolio is not a display case. It is a lab notebook. The goal is not to look finished. The goal is to show how you think, what broke, and how you fixed it.

If a case study does not have a specific problem and a specific proof link, I rewrite it.