The worst time to write an incident update is during the incident. You are tired, the facts keep changing, and the temptation is to write something vague that cannot be wrong. Vague updates are the ones customers screenshot.
This post gives you fill-in-the-blank wording for each stage of an incident: investigating, identified, monitoring and resolved. It also gives an outline for the postmortem. Each template has a short rule for what to put in the blanks, and the staging follows the incident-communication advice in Google's SRE chapter on managing incidents.
If your search was "incident communication template", copy the blocks below into wherever you publish updates. They work on any status page, including one you built yourself.
What rules apply to every incident update?
Four habits carry most of the quality of an incident update:
- Say what users experience, not what your system did. "Checkout fails with an error page" tells a customer something. "Elevated error rates on the payments service" tells them you are protecting yourself.
- Give a time for the next update, then keep it. The commitment matters more than the content. An update that says "next update by 15:30 UTC" and arrives at 15:30 is worth more than a clever paragraph.
- Use one timezone, and name it. Write UTC in every timestamp so people in other regions do not have to translate. The RFC 3339 timestamp format makes that unambiguous.
- Do not guess at a cause or an end time. Say what you know. If you do not know, say that you do not, and say when you will.
Template 1: Investigating
Post this as soon as you have confirmed users are affected. Do not wait for a cause.
Title: [Affected feature] is [failing / slow / unavailable]
Status: Investigating
We are investigating reports that [what users see, in plain words].
This affects [who: all users / users in a region / users of a feature].
[Anything users can do right now, or "No action is needed."]
We will post another update by [time, UTC].
Filled in:
Title: Checkout is failing for some customers
Status: Investigating
We are investigating reports that checkout shows an error page after
payment details are submitted. This affects customers paying by card.
Customers paying with a saved invoice are not affected. Please do not
retry the payment; we will confirm when it is safe.
We will post another update by 15:30 UTC.
Rule for the blanks: if you are not sure who is affected, say "some customers" and say what you are checking. Do not write "a small number of users" unless you have the number.
Template 2: Identified
Post this when you know what is wrong, even if you have not fixed it.
Title: [Same title as the investigating update]
Status: Identified
We have identified the cause: [one plain sentence, no internal names].
[What is still affected, and what has recovered.]
We are [the action in progress, in plain words].
[Time estimate if you have a real one, otherwise: "We do not have an
estimated time to resolution yet."]
We will post another update by [time, UTC].
Filled in:
Title: Checkout is failing for some customers
Status: Identified
We have identified the cause: a change we released at 14:05 UTC
affects how card payments are confirmed. Card payments are still
failing. Invoice payments and everything else are working normally.
We are rolling the change back.
We do not have an estimated time to resolution yet. We will post
another update by 15:00 UTC.
Rule for the blanks: "we are rolling back" and "we are waiting on a provider" are both fine. "We are working on it" tells the reader nothing and should be replaced with the specific action.
Template 3: Monitoring
Post this when a fix is in place and you are watching it hold. Do not skip this stage; it is the one that stops a premature "resolved" from being reopened an hour later.
Title: [Same title]
Status: Monitoring
A fix has been applied and [what you observe: error rates are back
to normal / checkouts are completing]. We are monitoring to confirm
it holds.
[Anything users need to do, for example retry a failed action.]
We will post a final update by [time, UTC], or sooner if anything
changes.
Rule for the blanks: state what you observe, with a measurement if you have one ("no failed checkouts in the last 20 minutes"), not what you hope.
Template 4: Resolved
Post this when you have watched the fix hold for as long as you said you would.
Title: [Same title]
Status: Resolved
This incident is resolved. Between [start time] and [end time] UTC,
[what users experienced, in one sentence].
[Impact in numbers if you have them: how long, what share of
requests or customers, what data was or was not affected.]
[Anything customers need to do: retry, check an order, or "No action
is needed."]
We will publish a summary of what happened by [date].
Filled in:
Title: Checkout is failing for some customers
Status: Resolved
This incident is resolved. Between 14:05 and 15:12 UTC, card
payments at checkout failed with an error page. Invoice payments
were not affected. Orders were not charged twice. If you saw an
error and your order does not appear in your account, please try
again.
We will publish a summary of what happened by Friday.
Rule for the blanks: state the real window, from when users were first affected (which can be earlier than when you noticed) to when you confirmed recovery. Under-reporting the start time is the most common way an update loses trust.
Template 5: Postmortem outline
A postmortem should be blameless and specific, as the SRE book's chapter on postmortem culture puts it. Publish one when the incident taught you something customers or other engineers can use. It does not need to be long. It needs to be specific.
Title: [Date]: [what happened, in plain words]
Summary
[Two or three sentences: what broke, for whom, for how long.]
Impact
[Start and end time in UTC. What users saw. How many, as a number or
a percentage. What was not affected.]
Timeline (UTC)
[HH:MM] [What happened or was observed.]
[HH:MM] [When we first knew, and how: an alert, a customer report.]
[HH:MM] [What we tried, including what did not work.]
[HH:MM] [Fix applied.]
[HH:MM] [Recovery confirmed.]
Cause
[What actually went wrong, in terms a customer can follow. If there
was more than one factor, list each.]
Why we did not catch it sooner
[The detection gap, owned in the first person: "We did not alert on
X because Y."]
What we are changing
[Each change as a specific action with an owner or a date. Leave out
anything you do not intend to do.]
Rule for the blanks: write "we", not "the system". If the cause was a change you made, say so. Customers forgive mistakes far more readily than they forgive an explanation that seems built to avoid one.
What should an incident update leave out?
- Apologies that replace information. One sentence of apology is plenty. The rest of the space belongs to facts.
- Internal names. Hostnames, cluster names and ticket numbers mean nothing to a customer and can expose things you would rather not publish.
- Percentages without a base. "Affecting 10% of requests" is meaningless if the reader cannot tell which requests.
- Closing the incident early. "Resolved" should follow a monitoring period you can name.
Using the templates on the page itself
Save these five somewhere your on-call engineer can reach them at 3 a.m., so the first update takes thirty seconds rather than ten minutes.
Three other pages cover the surrounding questions:
- Our guide on incident communication templates goes through the timing rules behind each stage.
- Status page best practices covers what the page itself should show.
- The post on status pages that cannot lie explains why the numbers in an update need to match what monitoring saw.
Planned downtime is a different case with different wording, covered in maintenance windows without false alerts.
RealUptime Status models incidents through these same four stages, drafts the first update when a monitor confirms a real transition, and emails every posted update to subscribers. Start a free status page and paste these in; no card is needed.