How to write outage and maintenance notices people actually read
Updated . Guidance from running status pages, not a standard; adapt it to your customers.
During an outage, customers want three things answered quickly: is it you or is it them, what is broken, and when will they hear more. A short, honest notice posted early saves more support tickets than a detailed one posted late. The generator above writes the text for each stage; this guide explains what each stage should say and why.
What each stage should say
Investigating. Post as soon as you have confirmed users are affected, before you know the cause. Name the affected part in the customer's words ("checkout", "login", "the API"), say what they may see, when it started and when the next update comes. Avoid guesses about the cause; a wrong guess has to be taken back in public.
Identified. You know what is wrong and are working on it. One plain sentence about the cause is enough ("a database failover did not complete"). If there is a workaround, this is where it belongs, because it helps people right now.
Monitoring. A fix is live and you are watching it. Ask anyone still seeing the problem to retry and get in touch: they are your best early warning that the fix did not fully work.
Resolved. Say that things are back to normal, the time window, what users may have seen and, briefly, the cause. Promise a review only if you will publish one. Do not blame a vendor by name in the first message; explain what you will change.
Scheduled maintenance. Give the window with a time zone, what will be unavailable, and whether customers need to do anything. Most do not, and saying so prevents worried replies. Link the status page for live updates.
Maintenance complete. Short and specific: what was worked on, when it finished, and where to report anything that still looks wrong.
Examples for every stage
Generated by this tool with the plain tone for a fictional "Acme API".
Investigating
Investigating: problems with Acme API We are investigating reports that checkout and webhooks are not working as expected. Users may see: some requests fail with a 503 error. Started at 14:05 UTC. Next update within 30 minutes.
Identified
Identified: Acme API problem found We have found the cause: a database failover that did not complete. Affected: checkout and webhooks. Users may see: some requests fail with a 503 error. We are working on a fix. Next update within 30 minutes.
Monitoring a fix
Monitoring: fix deployed for Acme API A fix has been deployed and we are monitoring the results. Affected: checkout and webhooks. If you still see some requests fail with a 503 error, please retry and contact us if it continues. Next update within 30 minutes.
Resolved
Resolved: Acme API is working normally Checkout and webhooks are working normally again. From 14:05 to 15:20 UTC, users may have seen: some requests fail with a 503 error. Cause: a database failover that did not complete. We will review what happened and how to prevent it.
Scheduled maintenance
Scheduled maintenance: Acme API We will carry out planned maintenance on the dashboard and API. Window: Sat 25 Oct 02:00 to 03:00 UTC. During the window: the dashboard and API will be unavailable for up to 30 minutes. No action is needed from you. Updates: https://status.example.com
Maintenance complete
Completed: Acme API maintenance The dashboard and API are back in service. Finished at 03:00 UTC. Everything should be working normally.
Timing and channels
- Post the first notice fast. Many teams aim to post within 10 to 15 minutes of confirming an incident. The first notice can be one line.
- Keep the promise in "next update". If you said 30 minutes, post in 30 minutes even if the news is "still investigating". Stretch the interval to an hour once a fix is being monitored.
- Status page first, everything else points to it. Emails, posts and WhatsApp or SMS messages should be short and link the status page, so there is one place with the full, current story.
- Fit the channel. A post should stay within 280 characters including the link; an SMS within 160 characters avoids being split. The counter above shows the length.
- Announce maintenance early, then remind. A few days ahead for routine work, a week or more for long downtime, a reminder shortly before, and a "complete" message after.
Posting it on a status page
If you run a status page with Vigil, each incident update goes on the public page and every incident gets its own permanent link (/s/<your-page>/incidents/<id>) with a share card, which is the link to paste into the email, post or message you wrote here. Status page subscribers get the update by email; the free plan includes 25 subscribers. Vigil does not post to X or send WhatsApp or SMS messages to your customers for you, so those versions are for you to send. To know about an outage before your customers do, start with an outside check of your site.
FAQ
What should the first outage notice say?
Say what is affected, what users may see, when it started and when you will post the next update. You do not need the cause yet: 'We are investigating problems with checkout; some payments fail; next update in 30 minutes' is enough, and it stops the flood of support tickets.
How often should I update during an outage?
Post at the time you promised, even if nothing has changed. A common rhythm is every 30 minutes while users are affected and an hour or more once a fix is being monitored. Silence reads as 'nobody is working on it'.
How far ahead should I announce planned maintenance?
Far enough for customers to plan around it: a few days for routine work, a week or more for long downtime or anything that needs action from them. Repeat the notice shortly before the window starts and post again when it ends.
Should the resolved message explain the cause?
Briefly, if you know it, in plain words and without blaming a vendor. Say when it started and ended and what users may have seen. A longer write-up (a post-incident review) can follow later and be linked from the incident.
Does this tool store what I type?
No. The notice is assembled in your browser as you type. If you use the share link, the fields travel in the link itself; the page rebuilds the notice from them and nothing is saved on our side.