A good post-mortem is a piece of technical writing. It should be readable by someone who wasn't there, convey the timeline clearly, and suggest concrete changes.
Most are none of these things. They're a wall of Slack screenshots.
Here's how to write one that people will read.
The structure
1. Summary (3 sentences). What happened. Impact. Duration. That's it.
2. Timeline. Precise times, in UTC. Not 'around 3pm.' 14:02 UTC. Every event gets one line.
3. Impact. Quantified. 'X% of checkout traffic failed between 14:02 and 14:17.' Not 'some users affected.'
4. Root cause. What broke and why. Not who. If the answer is 'human error,' keep going why did the system allow human error to reach production?
5. Action items. Concrete. Owner. Due date. 'Add validation to config pipeline @alice 2 weeks.' Not 'be more careful.'
The tone
Write it like you're explaining to a curious outsider. No inside jokes. No 'as you all know.' Future readers don't know.
Keep it honest. If the cause was something embarrassing, write it down. Post-mortems that hide the ugly parts are worthless to the reader.
The distribution
The best post-mortems get read by people outside the team. Share them. Put them in a searchable archive. Reference them in design reviews. ('We tried this in 2024, see post-mortem 42.')
Institutional memory lives in good post-mortems. Bad ones evaporate the day they're written.
Written by Dr. Samson Tanimawo
BSc · MSc · MBA · PhD
Founder & CEO, Nova AI Ops. https://novaaiops.com
Top comments (0)