An incident update is the shortest honest sentence about what is broken, who it affects, and when you will say more. These templates give one for each state of an incident on a status page, one for scheduled maintenance, and the rules that keep a status page believed. Replace the text in brackets; keep the rest.
The four states
A status page incident moves through four states, and each update names the state it is in. OrgOrg Status uses these four; most status pages use the same words.
| State | What it means | When to post it |
|---|---|---|
| Investigating | You know something is wrong and not yet why | Within minutes of the alert, before you know the cause |
| Identified | You know the cause and are working on it | As soon as the cause is confirmed, not when the fix is ready |
| Monitoring | The fix is in place and you are watching it hold | When the error rate is back to normal |
| Resolved | The incident is over | When you would stop watching |
Investigating
[Service] is [degraded / unavailable] for [some / all] users. We are investigating [elevated error rates / slow responses / failed logins] on [service] since [HH:MM UTC]. [What a user sees: "API requests return 503 errors", "the dashboard does not load".] Next update by [HH:MM UTC].
Say what is affected and what it looks like from outside. Do not guess the cause. Give the time of the next update, and post one at that time even if nothing has changed.
Identified
The cause of the [service] [outage / degradation] is identified. [One sentence of cause a customer can act on: "a configuration change to our database pool", "a failure at our email provider".] We are [rolling back the change / failing over to a second region / working with the provider]. [What still does not work.] Next update by [HH:MM UTC].
Name the cause in words a customer can use, not the internal component. If the fix will take a known time, say it; if not, say when you will know.
Monitoring
A fix for the [service] [outage / degradation] is in place. Since [HH:MM UTC], [error rates are back to normal / logins succeed / queued jobs are draining]. We are monitoring for [the next 30 minutes / an hour] before we close the incident. [Anything a user must do: "refresh the page", "retry a failed upload".]
Say what "fixed" looks like, so a customer still seeing the problem knows to tell you.
Resolved
Resolved. [Service] was [unavailable / degraded] from [HH:MM] to [HH:MM UTC] on [date]. The cause was [one sentence]. [What was lost, or that nothing was: "No data was lost."] [Whether a postmortem follows: "A full write-up will be posted here within three working days."]
The resolved note is the one people read a week later. It names the start, the end, the cause, and the loss, in that order.
Scheduled maintenance
Scheduled maintenance: [service], [date], [HH:MM to HH:MM UTC] ([HH:MM to HH:MM local]. [What happens: "the API will return 503 for up to ten minutes while the database is upgraded".] [What a user should do: "pause scheduled jobs that run in this window".] We will post here when the work starts and when it ends.
Post it at least a week ahead, repeat it the day before, and post the start and the end as updates.
The rules
- Post the first update before you know the cause. A status page that is silent for the first twenty minutes of an outage teaches customers to check Twitter instead.
- Give every update a next-update time, and keep it. "Next update by 14:30 UTC" is a promise. Posting "no change" on time is better than news late.
- Times in UTC and in your main local zone. A customer in another zone converts one of them.
- Describe impact from the outside. "Logins fail" is impact. "The auth service is at 40 percent capacity" is a diagnosis nobody can act on.
- Never downgrade silently. If the fix does not hold, post Investigating again and say so.
- The resolved note names the cause and the loss. It is the only update most people will read.
In OrgOrg Status, a person posts each update with its state, the affected services, and the message; a subscriber gets each one by email, in Slack, or by webhook; and an incident that a paged On-Call rotation opened carries its services from the start. The page writes no text for you. These templates are the text.