How to Write a Project Case Study (Not Just a Link to a Repo)

TL;DR - A case study is a written narrative about a project: the problem, your approach, your decisions, and what you learned. - You don't need to write one for every project. Focus on 1-2 strong ones. - The structure that works: problem, constraints, approach, key decisions (with trade-offs), outcome, and reflection. - Where to publish: a personal site, a detailed GitHub README, a LinkedIn article, or dev.to. - What interviewers get from reading a case study that they can't get from a repo: evidence that you think, not just code.

A GitHub repo answers one question: what did you build?

A case study answers different questions, the ones interviewers actually care about: why did you build it this way? What problems did you run into? What would you change? What did you learn?

Every engineer has opinions about their work. Most candidates never write those opinions down. Writing a case study for even one project puts you in a different category from the majority of applicants, because it shows your thinking process directly, without requiring an interview to reveal it.

What a Case Study Is (and Isn't)

A case study is a written narrative about a project. It's not documentation. It's not a tutorial. It's not a sales pitch for how great your app is.

A case study is closer to a post-mortem or a design document: honest, specific, and focused on decisions. Good engineering case studies are interesting because they acknowledge difficulty and trade-offs. Bad ones are marketing copy that describes features without reflecting on process.

The goal is to let a reader understand: - What problem you were trying to solve - How you thought about solving it - What decisions you made and why - What worked, what didn't, and what you'd do differently

That's it. You're not trying to prove you're brilliant. You're showing that you think carefully and learn from experience.

Which Projects Deserve a Case Study

Not every project needs one. In fact, writing thin case studies for weak projects is worse than writing nothing, because it highlights the weakness.

Save case studies for projects where at least one of these is true:

You made an interesting technical decision. You chose between two approaches and had real reasons for your choice. You ran into a constraint that pushed you toward an unexpected solution.

You solved a real problem. The project exists because someone (including you) had an actual need. Not "I wanted to learn React," but "I was frustrated with X and built Y to fix it."

You have something to reflect on. The project was hard in ways that taught you something. It has a section of code you're proud of and a section you'd rewrite.

You can explain it in depth. You built enough of it to have opinions. You remember why things are the way they are.

For most candidates, this means 1 or 2 projects out of their entire portfolio. That's fine. A well-written case study on one strong project is worth more than thin writeups on five mediocre ones.

If you're not sure which project to pick, revisit how to pick a portfolio project first. The project selection and the case study work together.

The Structure of a Strong Case Study

There's no mandatory format, but this structure consistently produces readable, useful case studies.

1. The Problem

Open with the problem, not the solution. What gap or frustration motivated the project? What doesn't exist that should? What were you trying to do before you built this, and what was broken about that process?

This section should be short: two or three paragraphs at most. The goal is to give the reader a reason to care about the rest of what you're writing.

Avoid: "I wanted to learn Next.js." That's a goal for you, not a problem worth solving.

Better: "I manage several freelance contracts and was tracking payment schedules in a spreadsheet that kept breaking. I wanted something that would remind me when invoices were overdue without me having to open it manually."

The problem statement roots the whole case study. It's the "why" that makes all your decisions coherent.

2. The Constraints

Every real project has constraints. Constraints are what make engineering decisions interesting.

What were yours? Common ones for portfolio projects: - Building it solo, so architectural complexity has to be manageable - Free hosting only, which rules out certain database options - A specific technology you wanted to get experience with, which might not have been the "easiest" choice - A timeline (you wanted to finish it before a job search started)

This section doesn't need to be long. A paragraph is enough. But naming your constraints shows self-awareness. It also preempts unfair criticism: if an interviewer wonders why you didn't use a more sophisticated setup, your case study can answer that before they ask.

3. Your Approach

This is where you describe what you built and how. Not every feature, just the core decisions.

What did the architecture look like? How did you handle the main problem? What was the first thing you built, and why?

This section should read like you're explaining your approach to a colleague, not like you're writing technical documentation. Use plain language. Be specific about technologies and why you chose them, but don't list every dependency.

If you made a decision that goes against the obvious path (you chose a relational database when most people would use a document store, or you avoided a popular library for a specific reason), explain that here. This is the most interesting material in most case studies.

4. The Hard Parts and the Decisions

This is the section most candidates skip, and it's the most valuable one.

Where did you get stuck? What took longer than expected? What did you get wrong the first time and fix? What were the moments where you had to choose between two approaches and couldn't find clear guidance?

Write about these honestly. A candidate who writes "getting the real-time updates to work was straightforward" and a candidate who writes "I spent three days trying to use WebSockets before realizing my hosting tier didn't support persistent connections, so I switched to polling with a 10-second interval" are sending very different signals. The second candidate is more interesting to hire.

You don't have to make every decision sound catastrophic. A calm, matter-of-fact account of a problem and how you worked through it is exactly what interviewers want to see. It's what they'll ask you about in the technical interview anyway.

5. The Outcome

What does the project do now? Is it deployed? Are you using it yourself? Did it actually solve the problem?

Be honest here too. It's fine to say "I built most of the core features but haven't implemented the email reminder system yet." It's better than claiming the project is complete when there's an obvious missing piece.

If the project is live, link to it. If there are specific features worth pointing reviewers toward, mention them. If there are known limitations you'd address next, name them.

6. The Reflection

A short section at the end on what you'd do differently is optional but powerful.

One or two paragraphs: what would change if you started over today? What did the project teach you that you'll carry into future work?

This doesn't have to be an exhaustive self-critique. Even a single concrete observation ("if I built this again I'd separate the business logic from the controllers earlier, because it became hard to test once things were tangled together") shows that you extracted lessons from the process.

A Note on Length

Case studies don't need to be long. 600-1200 words is a good target for a personal site or blog. If you're publishing in a detailed GitHub README, you might go longer. If you're writing a LinkedIn article, 800 words is probably the ceiling before readers drop off.

The common mistake is either too short (two paragraphs that describe features without reflection) or too long (a 3,000-word essay that buries the interesting decisions in technical minutiae).

Aim for something a hiring manager could read in 4-5 minutes and a senior engineer could read in 10. Both audiences matter.

Where to Publish

You have four realistic options, and they're not mutually exclusive.

Your personal site

The highest-effort option and the most professional. A personal site with a Projects section that links to case studies makes your portfolio feel complete. It also gives you full control over formatting, visuals, and how the work is presented.

If you have a personal site and you're not using it to publish case studies, you're leaving value on the table.

A detailed GitHub README

The lowest-effort option for reaching reviewers. If your README goes beyond setup instructions and documents your approach, decisions, and reflections, it's functioning as a case study even if you don't call it one.

See how to write a README that helps your portfolio for what to include. The README and the case study structure are closely related.

A LinkedIn article

Publishing a case study as a LinkedIn article gets it in front of your network and any recruiter who visits your profile. LinkedIn articles appear in search results and are indexable by Google.

The main downside: LinkedIn's article editor is mediocre, and formatting code or diagrams is clunky. For a text-heavy case study with limited code, it works well.

dev.to

dev.to is a community for developers with a clean writing interface and a built-in audience. Publishing there can get your work in front of people who wouldn't otherwise see it. If your case study teaches something generalizable (a problem you solved, a library you evaluated, a mistake you made), it may get picked up and shared.

The main upside beyond distribution: dev.to posts can appear in Google results for technical queries, which occasionally leads to recruiter outreach.

What Interviewers Get From a Case Study

When an interviewer reads a case study before your interview, the conversation changes.

Instead of starting from scratch ("tell me about a project you've worked on"), they can go deeper ("I read about the polling vs. WebSocket decision you made. Can you talk about how you'd approach that differently given more resources?").

This is a better conversation for you. You're not recapping context. You're discussing substance.

Case studies also filter for the right opportunities. A hiring manager who reads your case study and thinks "this person thinks the way we think" is more likely to move you forward. One who reads it and finds it uninteresting is probably not a company where you'd thrive anyway.

There's also a less obvious benefit: writing the case study prepares you for interviews. The act of articulating your decisions in writing makes you more fluent in talking about them verbally. If you've written a 1,000-word case study about a project, you can answer any interview question about it without struggling to remember the details.

Common Mistakes

Describing features, not decisions. "The app lets users create accounts, add items, and share lists with friends." This describes the app, not your work. Focus on decisions.

Avoiding the hard parts. If you only write about what went well, you're writing marketing copy, not a case study. The hard parts are what make it worth reading.

Too much code. Embedding large code snippets slows readers down and often obscures the narrative. Include code when a specific snippet illustrates a decision, not as decoration.

No reflection. A case study without reflection is a README. Add at least a paragraph on what you learned or would change.

Publishing it and never mentioning it. Link to the case study from your GitHub repo, your LinkedIn profile, and your resume. If it lives on a personal site, make sure the URL is easy to find.

For your GitHub profile to support your case studies well, read how to build a GitHub profile that gets you hired. The two work together.

If you want structured support developing and writing up your portfolio projects, here's how the Globally Scoped program works.