The fix isn't more discipline. It's a format built around how people actually read: a three-line summary at the top, a timeline underneath, owned action items with deadlines, and everything else pushed into an appendix. This article walks through that structure and why each piece earns its place.
Key takeaways
- Put a three-line summary first: what broke, how long, what's changing. Most readers stop there, and that's fine. That's where the leverage is.
- Action items with a named owner and a real deadline are the product. A postmortem that ends in a paragraph of prose rarely changes anything.
- Google's SRE book is blunt about review: "An unreviewed postmortem might as well never have existed."
- Blameless writing isn't a nicety. It's what keeps people telling you the truth about what happened.
Why postmortems go unread
The standard postmortem template grew by accretion. Every time an incident review missed something, someone added a section: contributing factors, detection analysis, customer impact matrix, lessons learned, what went well. Each section is individually defensible. Together they produce a document that takes forty minutes to read, so almost nobody reads it.
That matters because the document is the delivery mechanism for the learning. PagerDuty's postmortem guide puts the purpose plainly: "Well-designed postmortems allow your teams to iteratively improve your infrastructure and incident response process" (PagerDuty Postmortem Documentation). A postmortem nobody reads improves nothing. It's a compliance artifact.
In my experience running incident reviews for client teams, the completeness-first template fails in a predictable way: the author spends hours filling in sections, the document gets posted to a channel, two people react with an emoji, and the same class of incident recurs a quarter later. The information was captured. It was never transmitted.
The format that gets read
Structure the document in three layers, ordered by how many people will actually read each one:
- The three-line summary. What broke, how long it was broken, and what's changing so it doesn't happen again. This is the only part most of the organization will ever see, so write it last and write it carefully. If an executive or an engineer on another team reads nothing else, they should still come away with the one thing you need them to know.
- The timeline. Timestamped, factual, and free of interpretation: when the change shipped, when the alert fired, when a human engaged, when mitigation landed, when service recovered. Responders and reviewers read this layer. It's also where detection and response gaps become visible without anyone having to editorialize about them.
- Everything else. Root cause analysis, contributing factors, what went well, supporting graphs. Keep it, but put it below the fold. The people who need this depth will scroll. The people who won't scroll were never going to read it anyway, and forcing it above the summary just guarantees they read nothing.
The uncomfortable part of this design is accepting that most readers never make it past the summary. That's not a failure of the format. That's the format working: it moves the highest-leverage information to the place where attention actually exists.
Action items are the product
The narrative explains the incident. The action items are what change the outcome of the next one. Two properties separate action items that get done from action items that decorate a document:
- A named owner. A person, not a team. "Platform team to investigate" is where follow-ups go to die.
- A real deadline, tracked where work is tracked. If your team lives in Jira or Asana, the action item lives there too, linked from the postmortem. A due date that exists only inside a document is a suggestion.
Google's SRE book treats prioritized action items as one of the defining criteria of an effective postmortem, alongside documenting the incident and understanding its root causes (Site Reliability Engineering, "Postmortem Culture: Learning from Failure"). Atlassian's incident handbook goes the same way: the postmortem isn't finished when the document is written, it's finished when the follow-up work is scheduled (Atlassian Incident Management Handbook).
A useful forcing function: cap the list. Three to five action items with owners and deadlines beat fifteen aspirational ones. If everything is a follow-up, nothing is.
Blameless writing keeps the information flowing
Format determines whether a postmortem gets read. Culture determines whether it gets written honestly in the first place. The SRE book's framing is the one worth internalizing: "A blamelessly written postmortem assumes that everyone involved in an incident had good intentions and did the right thing with the information they had." And its corollary: "You can't 'fix' people, but you can fix systems and processes to better support people making the right choices."
This isn't about sparing feelings. It's mechanical. The engineer who typed the bad command is the only person who knows exactly what the runbook said, what the terminal showed, and why the action looked correct at the time. Write postmortems that punish that person and the next incident's timeline will be vague in precisely the places you need detail. PagerDuty's guide describes the same foundation: "A successful postmortem process is based on a culture of honesty, learning, and accountability."
Review it, then actually distribute it
The SRE book's warning bears repeating: "An unreviewed postmortem might as well never have existed." A quick review by a senior engineer catches the two failure modes that quietly kill postmortem programs: root cause analysis that stops one level too shallow, and action items that are really just wishes.
Distribution is the last mile. Don't post a link and hope. Put the three-line summary directly in the channel or email, with the link underneath for people who want the timeline. The summary travels; the document gets clicked by the minority who need it. If your team runs on error budgets and SLOs, this is also the natural place to note the budget spend, which turns the postmortem into an input for prioritization instead of a standalone ritual.
Frequently asked questions
How long should a postmortem take to write? The summary and timeline should be drafted within a day or two of the incident, while memory and logs are fresh. The analysis can follow. A postmortem published three weeks late is read even less than usual, because the organization has already moved on.
Does every incident need one? No. Define the triggers up front: user-visible downtime, data loss, or an incident that took longer than a threshold to resolve. The SRE book recommends deciding these criteria before the incident, not during the argument about whether this one "counts."
Should the postmortem meeting replace the document? No, they do different jobs. The meeting builds shared understanding among the people involved; the document carries the learning to everyone who wasn't in the room, including people who join the team next year. The three-layer format above is what makes the document worth that job.
Need infrastructure work like this done right? See what I do or look at recent builds.
