How to write an incident report your customers will read

A postmortem is written for engineers. A customer wants three answers in two minutes. Here is the shape that gives them, with a full example.

The problem

After an outage, teams write a postmortem. It is usually written for engineers: the timeline to the second, the graphs, the names of the services involved, the discussion of what went wrong in which part of the system. That document is valuable, and almost none of it is what a customer wants to read.

A customer who could not pay, sign in or reach your API has three questions. What happened to me? Is it fixed? Will it happen again? An incident report answers those three in the customer's terms, in a page they can read in two minutes, and it is often the thing that decides whether they stay.

The hard part is not the facts. It is leaving out everything that matters only inside the company, without sounding like you are hiding something.

The shape

• A title that says what broke and when. "Checkout errors on 6 October 2026", not "Incident 2026-114".
• A summary in two sentences. What happened, for how long, and that it is fixed. Someone who reads only this should have the whole story.
• The impact. Who was affected, what they saw, from when to when with the time zone, and what was not affected. Say plainly whether any data was lost or exposed, even when the answer is no, because it is the question people are too polite to ask.
• What happened, in plain words. The cause as you would explain it to a customer on the phone. One paragraph.
• What we did. When you noticed, when you found the cause, when it was fixed. Times show you were on it.
• What we are changing. Two or three concrete changes, each one something a reader could check you did. "We will be more careful" is not a change.
• One apology, and what to do now. Apologise once, plainly. If customers need to retry, sign in again or check something, say so last, where it is easy to find.

A Markdown outline to start from:

# <What broke> on <date>

## Summary
<Two sentences: what happened, for how long, and that it is fixed.>

## Impact
<Who was affected, what they saw, from when to when, with the time zone.
What was not affected. Whether any data was lost or exposed.>

## What happened
<The cause in plain words. No internal names.>

## What we did
<Detected at, found at, fixed at, with times.>

## What we are changing
1. <The change that stops this cause.>
2. <The change that would have found it sooner.>

<One apology. What an affected customer should do now, if anything.>

A full example

A made-up shop, a 23 minute checkout outage, written for its customers:

Notice what it does not contain: the name of the engineer who made the change, the name of the configuration file, the payment company, the alert channel, the internal ticket. None of them helps a customer, and each one invites a question you do not need to answer.

What to leave out

• Blame. No names of people, and no "human error" as the cause. A setting that accepts 30 milliseconds for a payment is a design problem, and saying so is both kinder and more useful.
• Internal names. Service names, server names, team names and ticket numbers mean nothing outside, and they read as jargon at best.
• Guesses. If you do not know the cause yet, say so and publish when you do. A report that changes its story after publication is worse than one that came a day later.
• Security detail that helps an attacker. If the incident involved an attack or a weakness, say what was affected and what you changed, not how it could be done again.
• Supplier names. Even when a supplier caused it. "A service we depend on failed" is honest, and the responsibility to your customers stays yours. What you change, such as a second supplier or a fallback, is the part to describe.

When to publish

Within a few days, while people still remember the outage. Two to five working days is a good target: long enough to know the cause for certain, short enough that it is still news. For a long or serious outage, say in the resolved update on the status page that a full report will follow, and when.

Then link the report from that incident on the status page, so anyone who finds the incident later finds the explanation with it. If you send a note to affected customers by email, link it there too. The guide to status page updates covers what to post while the outage is still going on.

Not every incident needs one. A blip of two minutes that few people noticed needs a clear resolved update, not a report. Write one when customers lost money or time, or when the same thing has happened before.

How Upglory does it

On a resolved incident, Upglory can write an incident report for your team from the evidence its checks kept: a summary, the impact, what the evidence shows, the likely cause and follow-ups. One report costs 3 AI credits, from the plan's monthly allowance: 10 a month on Free, 100 on Solo, 500 on Team. If the report cannot be written, the credits come back.

The report is marked as written by AI from the evidence, to be read before it is shared. Copy it as plain text or Markdown, or start your incident review from it, which fills in the review's draft for you to edit before anything is saved.

It is written for your team, and it never appears on a status page. So the customer report in this guide stays yours to write: take the facts and times from ours, then publish your own and link it from the incident's resolved update.

The explanations page shows the report and what it is written from, and the docs cover the rest of Upglory.