Writing a project post-mortem without blame

Every developer has a story about a project that went sideways: a migration that took three weekends instead of one, a launch that broke checkout, a side project abandoned at ninety percent. Most of those stories are told once, over coffee, and then lost. A written post-mortem keeps the lesson and lets other people learn it without paying for it.

Writing one well is harder than it looks. It is easy to slip into a confession, a complaint or a defence. This post is about writing the other kind: calm, specific and useful to someone who was not there.

Decide who the post-mortem is for

Before you write a word, decide on the reader. A post-mortem for your own team can name internal systems and assume shared context. A public write-up on your blog has to explain more and reveal less. The structure is the same, but the level of detail changes.

For a public post, ask two questions about every detail:

• Does the reader need this to understand what happened?
• Is this mine to share?

Customer data, colleagues' names, internal hostnames and anything covered by an agreement with an employer stay out. If removing those details makes the story impossible to tell, write it for your team instead and publish a shorter, more general version later.

Write the timeline first

Start with what happened, in order, with as little interpretation as possible. A plain timeline does two jobs: it gives the reader something solid to stand on, and it forces you to separate events from opinions.

A useful format is one line per event, with a time or a day:

Mon 09:10  Deploy of the new image-resize worker
Mon 09:40  First report: thumbnails missing on new posts
Mon 10:05  Worker logs show out-of-memory restarts
Mon 10:20  Rolled back to the previous worker
Mon 10:30  Thumbnails generating again; backlog cleared by 11:15

That example is invented for this post, but the shape is what matters. Notice what is missing: no "unfortunately", no "someone forgot", no adjectives. Those can come later, in the sections built for them. If you were not keeping notes at the time, rebuild the timeline from commit history, deploy logs and chat messages, and say where you are unsure.

Look for causes, not culprits

The heart of a post-mortem is the question "why did this happen?". The trap is answering it with a person. "Alex pushed a bad config" is a description, not a cause. The useful question is why the system allowed a bad config to reach production without anyone noticing.

A simple technique is to keep asking "why" until you reach something you can change:

1. The worker ran out of memory. Why?
2. It loaded full-size images into memory before resizing. Why did that not show up earlier?
3. The test fixtures were all small images. Why?
4. Nobody had added a large file since the fixtures were created.

You will rarely find a single root cause. Most incidents come from several small things lining up, and it is fine to list three or four contributing factors. What matters is that each one points to something a process, a tool or a test could catch next time. This style is often called a blameless post-mortem; it does not mean nobody is responsible, it means the write-up focuses on how the system failed rather than who to punish.

Causes are only half of the analysis. Also write down what went well. It is tempting to skip this because it feels like spin; do not skip it. Things that went well are lessons too, and they are the ones people most often forget to keep doing.

In the example above, perhaps the rollback was quick because the previous image was still tagged and ready. That is worth writing down, because the next refactor of the deploy script might quietly remove it. Good monitoring, a clear runbook or a colleague who spotted the problem early all belong here.

Turn lessons into action items

A post-mortem without action items is a diary entry. A post-mortem with twenty action items is a wish list. Aim for a handful, and make each one concrete:

• Specific: "Add a 20 MB test image to the resize fixtures", not "improve testing".
• Owned: one person or role is responsible, even in a public version where you only say "the team".
• Small enough to finish: if an item needs its own project plan, link to that plan instead.

For a public write-up, it is worth coming back to the post a few weeks later and adding a short note on which items were done. Readers trust a post-mortem more when they can see it changed something. If you do update it, mark the update clearly with a date so nobody mistakes the new text for the original account.

Find a tone that is honest and calm

The tone of a post-mortem tells readers whether they can trust it. A few guidelines that help:

• Use "we" for decisions the team made, and "I" when it was your call. Do not hide behind the passive voice.
• State the impact plainly. If users could not log in for forty minutes, say so; do not write "some users may have experienced issues".
• Avoid both self-flagellation and defensiveness. The reader came for the lesson, not for your feelings about it.
• Do not speculate about other people's motives. Describe what they did and what information they had at the time.

Our community guidelines apply here as everywhere: no sharing other people's private information, and no turning a write-up into an attack on a person or a company.

A shape you can reuse

If you want a template, this one covers most projects, from a production incident to a side project you decided to shut down:

1. Summary: two or three sentences on what happened and the impact.
2. Timeline.
3. Contributing factors.
4. What went well.
5. Action items, with owners.
6. Open questions you could not answer.

Post-mortems for side projects are often the most honest posts a developer writes, and they pair well with a normal project write-up; see writing up a side project people can try for the cheerful sibling of this post.