Incident Post-Mortems: What to Document After an Outage

When something breaks badly enough, most IT teams do some version of a post-mortem. They talk through what happened, maybe send a summary to management, and move on.

Three months later, the same thing breaks for the same reason.

The problem isn't that they did a post-mortem. The problem is that the post-mortem produced words instead of changes. The documentation captured what happened but didn't produce anything actionable that stuck.

Here's how to do incident documentation that actually matters.

During the incident: capture as you go

The best post-mortem documentation starts during the incident, not after.

When you're in the middle of an outage, it feels like there's no time to document anything. But capturing a brief running log takes about ten seconds per entry and pays back disproportionately when it's time to write the post-mortem, respond to management questions, or troubleshoot a recurrence.

What to capture in real time:

• Timestamps for everything: when the issue was detected, when you started investigating, when you tried each fix, when service was restored
• What you tried and what the result was
• Key findings during diagnosis
• Who was involved and what they were working on
• Any communications sent to affected parties

This doesn't need to be polished. A running note in a document or a dedicated channel in your chat tool is enough. The goal is a timeline you can reconstruct later without relying on memory.

The post-mortem document

Write the post-mortem within 48 hours while things are still fresh. Waiting longer means relying on memory, and memory reconstructs events in ways that make sense rather than in ways that happened.

A complete incident post-mortem has six sections.

Incident summary. Two to three sentences. What broke, when, how long it was down, and the impact. This is what leadership reads first.

Timeline. A chronological account of the incident from first detection to full resolution. Use the real-time log if you kept one. Be specific about times. "We noticed around 3pm" is less useful than "14:47: alert fired for database connection failures."

Root cause. What actually caused the incident. Not the symptom, the cause. A server going down is a symptom. The cause is why it went down. Good root cause analysis follows the "five whys" pattern until it reaches something actionable. The cause of most outages is not hardware failure. It's a change that wasn't tested, a dependency that wasn't documented, or a failure mode that wasn't anticipated.

What we did to fix it. The resolution steps in order. This becomes runbook material for the same issue recurring.

What went well. Honest assessment of what worked. Detection was fast. The team communicated well. The rollback worked. These are worth documenting because they reinforce practices worth keeping.

What didn't go well. Equally honest assessment of what made things harder. Nobody knew the failover procedure. The monitoring didn't alert on the right thing. The runbook was outdated.

Action items are the only thing that matters

The sections above set up the only thing that actually prevents future incidents: specific, assigned action items with due dates.

Not "improve monitoring." That's a sentiment. "Add alert for database connection pool exhaustion with threshold of 80%, assigned to [name], due [date]" is an action item.

Every post-mortem should produce a short list of action items. Each one should be:

• Specific enough that someone knows when it's done
• Assigned to a specific person, not "the team"
• Given a due date
• Tracked somewhere until it's complete

If the action items don't get tracked, the post-mortem didn't prevent anything. It just documented a problem.

Blameless doesn't mean consequence-free

Post-mortems should be blameless in the sense that they're about systems and processes, not about finding a person to fault. Human error is almost always the proximate cause of incidents. But human error happens in environments that allow it. The question is what in the environment created the conditions for the error.

That said, blameless doesn't mean nobody is accountable for fixing things. The action items that come out of a post-mortem are someone's responsibility. That's accountability without blame: focus on the system, assign the fix.

The incident history as an asset

Individual post-mortems are useful. A searchable history of post-mortems is more useful.

Patterns become visible over time. If your monitoring keeps failing to catch issues before users report them, that's not three separate incidents, that's a monitoring problem. If the same system keeps having outages, that's a reliability problem. If every incident involves confusion about escalation paths, that's a process problem.

An incident history that gets reviewed periodically is a roadmap for systemic improvement. Without it, you fix the immediate problem each time and leave the underlying pattern intact.

Keep your post-mortems in one place and review them together at least quarterly. The recurring themes are where the leverage is.