Documentation: Postmortem

I’m fortunate enough to still keep in touch with friends from my bachelor’s degree every couple of days. We discuss software engineering the most, by sharing technical blog posts and news articles but also associated fields like politics, investments and company’s culture.

Last year on one autumn’s evening, one of my friends grabbed my attention by mentioning that he was writing a postmortem on his train back home because something had happened at work.

That moment I remembered I had seen public postmortems in the past like the monzo’s account payments outage and Revolut’s top-ups failing but it never crossed my mind that they could also be very useful privately to a team.

That a postmortem as a written document doesn’t necessarily need to be written only when there is a software incident with a high degree of criticality, i.e, when companies need to reassure users, clients or stakeholders.

That’s how I realised it would have been useful to have had postmortems in my previous workplaces. How many times I had colleagues, and also myself, saying things like: “Yes, we once had Y happening” and how those experiences stay only with those who lived it, until they are soon forgotten.

So I set myself up to look for different kinds of templates in order to create my own. Something more specific to my use case that could be version controlled, just like we do with RFCs at Candyspace.

When creating my own template, I realised that one of the things that usually grabs the attention of most engineers is when somebody explains an incident that occurred, the root causes and consequences, how they faced it and how they fixed it. Which are the goals of a postmortem.

Moreover, postmortems are valuable because they clarify and detail what happened to all the parties involved, and depending on the content and the level of detail, they can possibly be shared with the management team or even the client, with the added benefit that your future colleagues can also learn from your team’s past mistakes.

Unfortunately, it wasn’t long enough until I had to use the template myself. And only then, by submitting it as a pull request, I realised that it also gave an opportunity to everyone involved to provide their own input and understanding of the problem.

PS: When I was writing this article, I was pleased to find another one from Mathias Lafeldt that has a very similar template. If you are interested in introducing postmortems in your workflow, it is definitely worth a read.