Skip to main content

Structure of a Strong Capstone Write-Up

What This Concept Is​

A capstone case study is not documentation and not a pitch. It is a written argument that a reader can follow in about fifteen minutes, ending with the reader able to state four things out loud: what the problem was, what you built, how it worked, and what you traded off. If any of the four is hazy at the end, the case study has failed regardless of how polished the prose is.

The strong version has four load-bearing sections: Problem, Approach, Outcome, Tradeoffs. Everything else (context, operations, future work) is supporting tissue. If any of those four is vague, the whole case study collapses around them.

A case study is a genre with well-known conventions, not a format you invent. The conventions are boring on purpose: they free the reader to focus on your judgment rather than decode your document. Readers who have already read one good case study can read your next one at roughly twice the speed -- that reuse of mental schema is a gift you give them for free.

There is a deeper claim embedded in this structure: an engineer's case study is primarily about decisions, not about systems. A tutorial describes a working system. A case study describes why you made the choices that led to that system, and what would have to be different for you to have chosen otherwise. The difference is the difference between code that runs and engineering that defends itself.

Why It Matters Here (In the Capstone)​

The capstone proved you could ship. The write-up is how other engineers find out what you actually did. Without it:

  • recruiters and senior engineers cannot tell a real project from a tutorial
  • interview loops devolve into trivia because nobody can read your work in advance
  • your own judgment is invisible -- code alone does not surface the decisions behind it
  • the rest of Module 5 (portfolio, bio, specialization defense) has nothing to point at

After Semester 8 and 9, you already know what good technical prose looks like. This is where you produce one. It is also the single artifact that every subsequent concept in this module references back to -- the portfolio (cluster 2) points at it, the bio (cluster 3) links it, the defense (cluster 5) walks through it live.

Concrete Example: Skeleton With Section Lengths​

Below is a working skeleton. Target length is 1,500-2,500 words. Section lengths are in paragraphs (P) and should be treated as a budget, not a minimum.

SectionPurposeTarget length
Title + one-line summaryHook, 1 sentence1 line
Context (1P)Who is this for, what domain1 paragraph
Problem (2-3P)Concrete problem with one quantified constraint2-3 paragraphs
Approach (3-4P)Architecture, key choices, diagram3-4 paragraphs
Implementation highlights (2-3P)2-3 non-obvious technical moves2-3 paragraphs
Outcome (2P)What works now, measured2 paragraphs
Tradeoffs (2-3P)What you gave up on purpose2-3 paragraphs
What I'd do differently (1-2P)Retrospective, no whining1-2 paragraphs
Appendix (optional)Diagrams, ADR links, runbook pointersas needed

Every section except Appendix should read fine even if the reader never opens the repo.

Concrete Example: A Load-Bearing Opening Paragraph​

Bad opener (feels like a README):

"This project implements a multi-tenant inventory service using Go, Postgres, Redis, and Kafka. It uses microservices architecture deployed on Kubernetes with a full CI/CD pipeline."

Good opener (answers: problem, constraint, outcome):

"Three upstream feeds push inventory changes at different cadences and delivery semantics. A naive write path produced double-counts every time a feed retried. This write-up covers the idempotent ingestion layer I built to solve that -- what it costs, where it breaks, and what I would redo."

The second opener names a specific problem the reader can visualize in five seconds, a specific failure mode, and a promise about what follows. The first opener invites the reader to leave.

Common Confusion / Misconceptions​

Learners confuse a case study with a README, a demo script, or a résumé bullet. All three are downstream:

  • a README tells the reader how to run the project
  • a demo script tells a live audience what to look at
  • a résumé bullet compresses the project into ten words

A case study is the primary narrative the other three point at. If your only writeup is the README, your project is unreadable outside clone-and-run.

Burying the problem. Many first drafts open with "I built a distributed X using Y and Z." A reader who does not already care about Y and Z will leave. Open with the problem, always.

Treating tradeoffs as apologies. "I wish I had done X but I didn't have time" is a confession, not a tradeoff. A tradeoff is an honest statement of what you chose not to build and why that choice still looks right with hindsight. Write it in the active voice.

Mistaking length for depth. A 4,000-word case study is not twice as rigorous as a 2,000-word one; usually it is half as rigorous with twice the padding. Depth comes from specifics (numbers, diagrams with labels, named alternatives), not from word count.

How To Use It (In Your Capstone)​

Write in this order, not in the order the reader sees:

  1. One-sentence summary -- write this first; rewrite it last.
  2. Outcome (what works now, measured) -- pins the target.
  3. Problem -- justifies the outcome.
  4. Approach -- connects problem to outcome.
  5. Tradeoffs -- makes the approach honest.
  6. Implementation highlights -- only the two or three moves a peer would not have guessed.
  7. What I'd do differently -- retrospective paragraph, no apology.

Then cut 20%. Then show it to one person and cut another 10%.

Check Yourself​

  1. Can you state the problem in one sentence without using any project-specific noun?
  2. Does the "Outcome" section have at least one number in it?
  3. Does "Tradeoffs" include at least one thing you deliberately did not build?
  4. If a reader stopped after the opening paragraph, would they know the problem, the domain, and the shape of your answer?
  5. Does the write-up contain at least one decision whose alternative you considered and rejected, with a reason?
  6. Is there at least one ADR or design note you can link to, so a reader who wants the deep version can go there?

Mini Drill or Application (Capstone-scoped)​

Three drills, in order:

  1. Opener drill. Write the first paragraph of your capstone case study. Constraint: no tool names in sentence one; one number in sentence two; a promise about what follows in sentence three. Stop.
  2. Skeleton drill. Fill the section table above for your capstone with a one-line intent per section (e.g., "Tradeoffs: why I chose not to build multi-region replication"). If any row reads "TBD," that section does not yet exist in your head.
  3. Alternative drill. Pick one decision from your capstone. Write two paragraphs: what you chose, and what you rejected. Read them aloud. If the rejection paragraph is shorter than the decision paragraph, you probably never seriously considered the alternative.

Keep all three artifacts in your repo under library/raw/case-study/ as drafts; they are the seed of the full write-up.

Transfer / How This Synthesizes Prior Semesters​

The case study is not a new skill; it is ten semesters of skills arranged into one artifact. Each section of the skeleton is carrying material forward from a specific earlier semester:

If any of those semesters feels thin when you sit down to write, the write-up will feel thin in that section; the remedy is to revisit the module, not to reword the paragraph.

See also (integrative)​

Source Backbone​

Portfolio assessment packages evidence from the whole curriculum. These books provide the technical and professional backbone for the narrative.