A portfolio case study that clients actually read starts with the outcome, explains the problem in the client's terms rather than yours, shows two or three decisions you made and why, links to something they can open, and ends with what you would do differently. It fits on one page. Most developer case studies are written for other developers. This one is written for the person deciding whether to pay you.
That is the whole shift. A peer wants to know which state management library you used. A client wants to know whether you understood a problem like theirs and finished it. Write for the client, and put the technical detail where a curious reader can find it without the rest having to wade through it.
When a project deserves a case study
Not every project does. A short entry on your portfolio page (name, live link, your role, one hard thing) is enough for most. If you need that format first, what to put on a developer portfolio website covers it, and building a portfolio with no experience covers where the projects come from.
Write a full case study when at least one of these is true:
- It is the kind of work you want more of. A case study is an advert for the next project, so pick the projects you would happily repeat.
- There was a real problem in it, not just a list of features.
- You can show the result: a live product, a store listing, before and after screenshots.
Two good case studies do more than eight thin ones.
The structure
Seven short parts, in this order. Each is a heading or a short paragraph, not an essay.
- The outcome, as the title. What changed for the client, in one line.
- The situation before. Who the client was and what was not working, in their words.
- What made it hard. The constraint: a deadline, a legacy system, a budget, a platform rule.
- Two or three decisions. What you chose, what you did not choose, and why.
- The result. What happened after launch, stated only as far as you can stand behind it.
- What you would do differently. One honest paragraph.
- The link and the stack. Something they can open, and the tools in one line.
Lead with the outcome
The title does most of the work, because it is often the only part that gets read.
Weak: Booking App Case Study
Better: A booking app that let a two-person salon stop taking appointments by phone
The second title tells a reader with a similar business that this is relevant to them, before they have read a word of the body. It also forces you to know what the project was actually for, which is a useful test in itself.
Describe the problem the way the client would
Clients do not describe their problems in technical terms. They say "we kept double-booking people" or "the app was too slow and reviews were dropping", not "we lacked optimistic locking on the reservations table".
Use their language for the problem and save yours for the decisions. A reader with the same problem recognises it instantly, and that recognition is what makes them keep reading.
| Developer phrasing | Client phrasing |
|---|---|
| Migrated the backend from Firebase to Supabase | Cut the monthly hosting bill and made reports load in seconds |
| Implemented offline-first sync | The app keeps working in the basement where there is no signal |
| Refactored the checkout flow | Fewer people gave up halfway through paying |
Only use the client phrasing if it is true. If you do not know whether fewer people gave up, do not say so.
Show decisions, not tasks
"Built the login, built the dashboard, integrated Stripe" is a task list. Every developer can write one. What a client cannot get from anyone else is your judgement, so show it.
Pick two or three decisions and give each one a short paragraph: the options, what you chose, and the reason. For example: you could have built a custom admin panel, but the client's team already lived in spreadsheets, so you synced bookings to a sheet they could edit, which saved two weeks and meant nobody had to learn a new tool.
That paragraph tells a client you will think about their situation rather than build the default. It is the most persuasive part of the page.
Be careful with numbers
Results sell, but only real ones. Rules worth keeping:
- Use numbers only with the client's permission, and only ones you saw yourself.
- Say where they came from. "Bookings by phone went from most of them to almost none, by the owner's count" is honest and specific.
- Never round up into a claim. "Increased revenue by 300%" invites the obvious question, and if you cannot answer it, the whole page loses credibility.
- No numbers is fine. "The salon stopped answering the phone during haircuts" is a result. It does not need a percentage.
Permission, NDAs and client data
Ask before you write about client work, ideally before the project starts. Most clients agree, especially if you offer to let them read it first.
If they say no, you can still describe the type of problem without naming them: "a logistics company with a ten-year-old ordering system". Never imply more than you are allowed to.
Format: make it scannable
The reader decides in the first screen whether to keep going. Help them:
- Headings for each part, so someone can jump straight to the result.
- One or two screenshots or a short screen recording, near the top. Before and after is especially strong.
- Short paragraphs. If a section runs past three paragraphs, cut it.
- The live link visible without scrolling to the bottom.
If you collected a testimonial from the client, put one sentence of it here, attributed by name, next to the result. How to get testimonials from clients covers how to ask for one that says something specific.
End with what you would do differently
This is the part most people skip, and it is the part experienced clients look for. "If I did it again, I would set up error tracking on day one instead of week four, because the first real bugs were reported by customers rather than caught by us."
It reads as confidence, not weakness. It shows you finished the project, looked back at it, and learned something, which is exactly what a client hopes you will do on theirs.