Writing post-mortems people actually read

There is a graveyard inside every engineering organization, and it is full of excellent post-mortems. Thorough timelines, sharp analysis, honest accounting — and zero readers beyond the handful of people who lived the incident. The work was real. The learning was real. And it evaporated, because a finding that nobody reads is, for all practical purposes, a finding nobody had. Writing a post-mortem people actually read is not a cosmetic skill layered on top of the investigation. It is the step that decides whether the investigation mattered at all.

The reason this is hard is that the writer and the reader are in completely different states. The writer just spent hours inside the incident; every actor, acronym, and graph is loaded in their head. The reader is someone two teams over, three weeks later, who clicked the link out of mild curiosity and will give it ninety seconds before deciding whether to keep going. Everything that feels obvious to the writer is invisible to the reader, and everything the reader needs — context, stakes, the one transferable lesson — is exactly what the writer is most likely to skip because it feels too basic to write down. Good post-mortem writing is the discipline of relentlessly serving that reader instead of yourself.

Lead with the summary, because most readers stop there

The single highest-leverage paragraph in any post-mortem is the first one, and you should write it as if it is the only one anyone reads — because for most of your audience, it will be. In three or four sentences, a reader should learn what broke, who it affected and how badly, why it happened at the highest level, and what you are doing about it. No suspense, no buildup, no withholding the cause for dramatic effect. This is not a mystery novel; the reader already knows there was an outage, and making them dig for the punchline is a tax on the busiest, most senior people you most want to reach.

A useful test: imagine the summary is the only thing that gets pasted into a leadership channel or a weekly reliability review — because it will be. Does it stand alone? Does someone who reads nothing else come away with an accurate, fair picture? If the summary needs the rest of the document to make sense, it is not a summary, it is an introduction, and introductions are where readers leave. Put the conclusion at the top and let the people who need depth descend into it; never make depth the price of admission for the headline.

Write the timeline as facts, the analysis as judgment, and keep them apart

The body of a post-mortem does two different jobs, and confusion between them is what makes the genre feel untrustworthy. The timeline is a record of what happened, in order, stated as plainly and verifiably as possible: at 14:02 the deploy began, at 14:09 error rates crossed threshold, at 14:14 the first page fired, at 14:31 the rollback completed. Timestamps, not adjectives. A reader should be able to check any line against the logs and find it exactly true. The moment you write "the alert was unfortunately delayed" in the timeline, you have smuggled an opinion into the place that is supposed to be beyond dispute, and a skeptical reader starts discounting everything.

The analysis is where judgment belongs — the contributing factors, the why-behind-the -what, the honest reckoning with what the system made easy. Here you are allowed to interpret, to weigh, to say "this is the factor that mattered most." Keeping these two modes visibly separate does something subtle and important: it lets a reader trust the facts even where they might argue with the conclusions. People will disagree about analysis — that is healthy — but they should never have to wonder whether the events themselves were shaded to support a narrative. A timeline that reads like evidence and an analysis that reads like reasoning is far more persuasive than a single blended account that reads like a defense.

Use plain language, name the lesson, and respect the reader's time

The fastest way to lose a cross-team reader is in-group shorthand. The service nicknames, the internal acronyms, the "as everyone knows" assumptions — each one is a small door slammed in the face of exactly the outsider whose future bug you are trying to prevent. Write so that a competent engineer from another part of the company can follow it without a translator. Expand the acronym the first time. Say what the service does, not just its codename. This is not dumbing down; it is widening the audience from the few who already understand to the many who need to.

And be explicit about the lesson. Do not make the reader reverse-engineer the takeaway from a list of follow-ups; state it. "The deeper issue here is that our deploy pipeline has no concept of a risky change — every change moves at the same speed regardless of blast radius" is a sentence that travels. People will carry it into design reviews and planning conversations long after they have forgotten the specific incident, and that portability is the whole point. The best post-mortems leave the reader with one durable idea they can apply to systems you have never seen.

Finally, respect the reader's time as a feature of the format, not an afterthought. Use headings so people can navigate to the part they need. Put the dense forensic detail where motivated readers can find it but casual ones can skip it. Cut the sentence that exists only to prove how hard you worked. A post-mortem is competing for attention against everything else in a busy engineer's day, and the version that wins is rarely the most exhaustive — it is the one that respects the reader enough to be clear, honest, and exactly as long as it needs to be. Write that one, and your hard investigation finally does the thing it was for: it changes what other people do.