Write Your Blog Posts Like Incident Postmortems

It's the morning after an outage, and I have the postmortem open. I've had it open on a lot of mornings, as a VP of Engineering and then as a CTO.

The first sentence says what broke, who was affected, and for how long. Nothing comes before it.

Below that is the timeline, one line per event, in order. Then the cause, written in terms of the system everyone on the team already knows: the queue, the deploy, the config nobody remembered. Then what changed so it won't happen again.

Nobody builds suspense. Nobody opens with a story about the night it started. The reader is tired and wants to know if they're affected, so the answer goes first.

Now take those same engineers, a year or two later, writing the first post on their own company's blog. They open with a meandering intro. They build toward a reveal.

Technical founders already know the best format for B2B content. They wrote it after every bad night on call. They just don't think of it as writing.

What a postmortem gets right

I notice the best postmortems from other teams do something most blog posts don't. They don't hedge or soften the thing that went wrong. They say it straight.

That matters because readers are scanning. They have a problem, they want to know if your post solves it, and they have maybe ten seconds to decide. The good ones lead with the outcome—what broke, why it broke, what you changed. No preamble.

But here's the thing that actually makes them work: they explain the failure in terms of something the reader already has. If you're writing about queue retries, your reader already has queues. You're not introducing a concept. You're explaining why a familiar system behaved differently than expected. That's what lets them check your reasoning against their own infrastructure. They can run the same test.

The other move is scope. A postmortem never claims to be the one true way to run infrastructure. It's narrow on purpose. "This happened to us, this was the cause, this is what we changed." That restraint is trustworthy because it's falsifiable. A big claim about best practices is easy to argue with. A small, specific claim that holds up is harder to dismiss.

Isn't this just another template?

@rglullis wrote that he'd rather read something with a bit of personality than yet another engagement-optimized article that follows all the tropes. Fair. Isn't "write it like a postmortem" just one more trope?

I don't think so, because a postmortem is closer to the opposite of a growth template. A template optimizes for reach. A postmortem optimizes for a reader who has the same problem and wants to fix it. And the personality is in the form, not on top of it: what you chose to look at, what you got wrong, how bluntly you say so. That's why good postmortems are often the most memorable docs a team writes.

Then there's @mcphage's pet peeve: "Here's this thing I did once, and now I'll tell everybody how to do it as if I were an expert." The postmortem is the cure for that. Its whole convention is n=1 and scoped. We saw this once, here's what we think caused it, we're not sure it generalizes. That sentence is what stops a thing you did once from posing as expertise.

Not every post is a failure story, and the form bends for opinion pieces. The three habits still hold.

Technical founders don't struggle with content because they can't write. I ran engineering teams before I started companies, and I've read a lot of good outage writeups. Engineers write them well. Then the same people sit down to do "marketing" and produce something that reads like a landing page with paragraphs. They drop the discipline they already trust and copy the shape of content they've seen, which is exactly the shape their buyers skip.

The fix is to stop switching modes. A blog post is a postmortem on a problem your customer is about to have. Say what happened first. Explain it in terms of the system they run. Claim only what you saw, and no more.

That's it. No suspense, no warm-up, no pretending to be an expert on things you haven't measured.

The outage doc was always the better sales asset. It was the only thing you wrote for a reader with a real problem.