Writing a Technical Post-Mortem: What You Built, What Broke, What You Learned
TL;DR - A post-mortem is a written reflection on a project: what you built, what decisions you made, what went wrong, and what you'd do differently. - It's one of the strongest portfolio pieces a new engineer can produce because it shows judgment, not just output. - Structure it in five sections: context, decisions made, what went wrong, what you'd do differently, and what you learned. - Write about failure plainly. Excuses undermine the whole thing. Analysis is what makes it worth reading. - Publish it on your personal blog, as a GitHub README, or as a LinkedIn article.
Why Post-Mortems Matter for New Engineers
Your GitHub repo shows code. A deployed app shows the result. But neither one shows how you think about the work.
A post-mortem fills that gap. It's a written account of a project after it's done (or after something significant broke): what you set out to build, what technical decisions you made along the way, what didn't go as expected, and what you understand now that you didn't before.
Senior engineers write post-mortems as a matter of professional practice. Teams at companies write them after incidents. The fact that it's a professional norm means submitting one as part of your portfolio communicates something clear: you operate like an engineer, not just a student.
For new engineers, the post-mortem is especially useful because it lets you demonstrate qualities that are invisible in a GitHub repo. Self-awareness. Technical judgment. The ability to reason about tradeoffs. The willingness to say "I made a mistake and here's what I'd do differently."
Those are the traits hiring managers are trying to evaluate in interviews. A post-mortem puts them on paper in a way a resume can't.
What a Post-Mortem Is Not
Before covering the structure, a few things to clear up.
A post-mortem is not a victory lap. It's not a press release about what you built. If the writing focuses mainly on what worked and treats the problems as minor footnotes, it reads like marketing, not reflection.
A post-mortem is also not a list of complaints. "The documentation was bad, the tools were frustrating, the requirements kept changing" is a list of excuses. The reader can't learn anything from it, and it signals that you haven't thought carefully about what was actually in your control.
The purpose is honest analysis. What happened, what caused it, and what you now understand as a result. That's the whole thing.
The Structure
A strong post-mortem has five sections. They don't need to be labeled exactly this way, but the substance should be there.
1. Context and Goals
Open with what you built and why. This section should be brief. Two to four paragraphs at most.
Include: the project goal in plain language, the tech stack you used, and any relevant constraints (solo project, two-week timeline, learning a new framework for the first time).
This gives the reader the foundation they need to evaluate everything that follows. Without context, the decisions and mistakes have no frame.
Example: "I built a recipe management app using Rails and Hotwire. The goal was to let users save and tag recipes, and to get experience with Turbo Frames without relying on a separate JavaScript framework. I had about three weeks and was learning Hotwire for the first time."
Don't oversell it. Don't write a paragraph about how excited you were. Just establish what you were doing.
2. Decisions Made
This section covers the technical decisions you made and your reasoning at the time. Not with hindsight, but why you made each choice when you made it.
"I chose to store tags in a separate table and use a join model rather than a simple string column, because I expected to need to filter by tag later. That turned out to be more work than necessary for the scope of the project, but the reasoning made sense at the time."
This section is where you show that you were thinking, not just typing. The decisions can be right, wrong, or mixed. What matters is that you can explain the logic.
Keep it to two to five significant decisions. Don't document every function you wrote.
Good candidates for this section: database schema choices, architectural patterns you chose or rejected, framework or library decisions, choices about when to add a feature and when to scope it out.
3. What Went Wrong
Be specific and be honest. Vague statements like "I underestimated the complexity" are not useful. What specifically did you underestimate, and what happened as a result?
"I didn't write tests for the import feature. When I refactored the tag model two weeks later, the import broke silently. I didn't catch it until I tried to demo the app, by which point I'd made three other changes that all needed to be reviewed. It took four hours to untangle."
That's a useful failure. The reader learns what happened, understands the cause, and can see that you understand it too.
Write about failures technically. Not about how you felt. Not about the external circumstances. What broke, what caused it, and what the downstream effect was.
If nothing went significantly wrong, you can note that and explain what you were watching for. But be honest. Most projects have something worth reflecting on.
4. What You'd Do Differently
This section is the direct output of section three. For each thing that went wrong, what's the counterfactual?
This is not a wishlist of ideal conditions ("I would have had more time" is not useful). It's specific and actionable: "I would have written integration tests for the import flow before refactoring the underlying model. Even one test that covers the happy path would have caught the regression immediately."
Good "differently" statements are things you could actually do on the next project. They show that the failure produced a lesson, not just a memory.
5. What You'd Carry Forward
End with two to three takeaways. Not motivational statements ("I learned that persistence matters"), but concrete technical or process insights.
"I now write at least one integration test for any feature that touches multiple models before I consider it done."
"I'll reach for a simpler data model on solo projects unless I have a specific reason to expect that complexity."
"I was skeptical of database migrations at first, but having a clean schema history saved me hours when I had to roll back a column change."
These takeaways are what make the post-mortem valuable to a reader. They're the evidence that the reflection actually changed something.
Level of Detail
A post-mortem should read like a clear engineering writeup, not a journal entry or a technical thesis.
You don't need code snippets in most post-mortems. If you do include code, keep it to one or two short examples that illustrate a specific decision or mistake. More than that and it starts to feel like documentation.
Aim for 600 to 1,200 words for a post-mortem on a solo project. Long enough to cover the substance, short enough that someone will actually read it.
The test: could a software engineer who didn't build the project read your post-mortem and understand what happened and why? If yes, you've hit the right level of detail.
How to Write About Failure Without It Reading Like an Excuse
The tone problem comes up in almost every first draft. The instinct is to protect yourself, to frame failures as inevitable or external. That instinct undermines the whole thing.
A few principles that help:
Use first-person ownership. "I didn't write tests" rather than "tests weren't written." "I missed this requirement" rather than "this requirement wasn't clear." The former reads like an engineer who understands their work. The latter reads like someone trying to avoid accountability.
Avoid the word "but" after acknowledging a mistake. "I didn't write tests, but I was under a tight deadline" is an excuse. "I didn't write tests. When I refactored later, it cost me four hours I didn't have." That's an honest account.
Keep emotion out of the analysis. "I was frustrated when the database migration failed" doesn't help the reader. "The migration failed because I hadn't backed up the schema state before running it" does.
Be proportionate. If a mistake had small consequences, describe it as such. Don't inflate a minor error into a crisis. Don't minimize a significant one.
Where to Publish
You have a few good options, and the right one depends on the project.
Your personal blog. The best option if you have one. A post-mortem is exactly the kind of technical writing that builds your credibility over time. Link to it from your project README and from your portfolio. For more on starting a technical blog, read how to start a technical blog.
A detailed GitHub README. If you don't have a blog yet, you can include a "retrospective" or "lessons learned" section at the bottom of your project's README. It's less visible but still valuable for anyone who reviews the repo closely.
LinkedIn article. A post-mortem published on LinkedIn gets more reach than a personal blog post, especially when you're actively job searching. It shows up on your profile and can be shared. Writing online as a developer has real value for visibility, as covered in writing online as a developer to get hired.
A case study page on your portfolio site. If the project is a featured piece, a link from your portfolio to a full case study (which can include a post-mortem section) adds context that a GitHub link alone doesn't provide. The project case study format complements the post-mortem well.
Connecting Post-Mortems to Your Portfolio Strategy
A post-mortem doesn't replace a strong project. The project still needs to exist, be deployed, and have a clean codebase. But it adds a layer of context that separates candidates who can build things from candidates who understand what they're building and why.
Read how to pick a portfolio project if you're deciding which project to feature. A project worth building is usually a project worth reflecting on.
Write the post-mortem within a week or two of finishing the project, while the decisions are still fresh. The details fade fast. The specific error messages, the sequences of decisions, the exact moment you realized something wasn't working: those are the raw material of a useful post-mortem, and they get harder to reconstruct over time.
If you want structured support building a portfolio that gets you into interviews, here's how the Globally Scoped program works.
Interested in the program?