A postmortem document has a longer life than the meeting that produced it. The meeting happens once; the document gets found in search, linked from a ticket, and read by someone debugging a similar problem a year later who was not in the room and never will be. Writing for that second reader, not just the people nodding along in the meeting, is what separates a postmortem doc that earns its place in the wiki from one that gets written, filed, and never opened again.
What changed in 2026
- AI-assisted drafting produces the first-pass timeline. Tools that pull from the incident channel, deploy logs, and monitoring dashboards can assemble a rough timeline automatically, leaving the human writer to verify it and add the parts no log captures.
- Incident platforms auto-generate the doc skeleton. Tools like Rootly, FireHydrant, and incident.io now create a structured draft the moment an incident is declared, which means fewer teams start from a blank page.
- Docs are published to a searchable wiki by default. Fewer postmortems live in a folder only the author can find; most teams now expect the doc to be discoverable the same way any other internal documentation is.
- Lightweight near-miss versions became common. A short writeup for a caught-in-time problem, without the full template, keeps the habit cheap enough to apply more often than only after visible damage.
What a postmortem doc actually needs
Every section exists to answer a specific question for a specific reader. Skip a section and you are betting nobody will ever need that answer.
| Section |
Purpose |
Typical length |
| Summary |
What happened, impact, and current status at a glance |
Three to five sentences |
| Impact |
Who was affected, for how long, in concrete numbers |
A few bullet points |
| Timeline |
Timestamped facts, no interpretation |
A table |
| Contributing factors |
The process or system gaps, framed without blame |
A short bulleted list |
| Action items |
Fix, owner, due date, tracking link |
A table |
Write the summary last, put it first
The summary is the only part most readers will see. Leadership skimming for status, an on-call engineer searching for a similar symptom, a new hire orienting to a system — all of them want the top three sentences, not the full timeline. Write it after everything else is drafted, when the shape of the story is actually known, then place it first. A summary that says "checkout errors spiked for 40 minutes due to a bad config deploy, no data lost, rolled back at 14:22" does more work than a paragraph of hedged prose.
The timeline is a table, not a story
Resist the urge to narrate. A timeline written as prose invites interpretation and opinion to creep in before the facts are even established. A timeline written as a table of timestamp and observed fact is faster to write, faster to verify against logs, and faster for a reader to scan for the moment that matters to them.
14:03 Deploy of config change #4821 begins
14:06 Deploy completes; error rate begins climbing
14:11 First alert fires (checkout error rate > 5%)
14:14 On-call acknowledges, begins investigating
14:22 Root cause identified; rollback started
14:24 Rollback complete; error rate returns to baseline
Save interpretation, blame-free contributing factors, and lessons for the section built for them. The timeline is not the place to explain why something happened, just what happened, in order.
Making action items survive past the doc
An action item that lives only inside the postmortem document dies there. Every action item needs an owner, a due date, and a link to wherever the team actually tracks work — a ticket, not a bullet point that nobody revisits. For a longer discussion of the facilitation side of this, running the meeting where these get assigned is covered in how to run a postmortem; this guide is specifically about the artifact that outlives it.
Common mistakes
- A vague summary. "Some errors occurred and we fixed it" tells a future reader nothing they can act on. Name the system, the impact, and the fix.
- No numbers. "Users were affected for a while" is not impact; "1,200 failed checkouts over 40 minutes" is.
- Action items with no owner. An unassigned action item is a wish, not a plan, and it will not get done.
- A wall of narrative prose. If the timeline reads like a short story, it takes a reader ten times longer to find the one fact they came for.
FAQ
Who should write the postmortem doc?
Usually the incident commander or the engineer closest to the resolution, with input from everyone involved. One clear owner for the draft keeps the writing coherent; the review pass is where the group adds detail.
How long should a postmortem doc be?
Long enough to cover every section in the table above, short enough that someone can read the summary and timeline in under two minutes. Full technical detail can live in an appendix or linked logs rather than the main body.
Should every incident get a full postmortem document?
No. Reserve the full template for incidents with real impact. A near-miss or minor blip is better served by a short writeup: what happened, why, and the one action item, without the full structure.
Where should postmortem docs live?
Wherever the team already searches for documentation, not a dedicated folder only the author remembers. Discoverability is most of the value of writing it down at all.
Where to go next