Guide
How to write an incident update customers trust
· Written by the New Odyssey team, with AI help.
An incident update has one job: tell people what's true right now, so they can decide what to do. Customers forgive outages. What they don't forgive is being told something that turns out not to be true.
The short answer: say what's affected, since when, what you know and what you're doing, in plain words. Leave out anything you haven't confirmed: the cause, the fix time, how many people are affected. Post the next update when something changes, and say it's resolved only when it is.
The first update: four facts
Your first update should go out as soon as you know customers are affected. It needs four things.
- What's affected, in the customer's terms. "Card payments fail at checkout" beats "elevated error rates on the payments service".
- When it started, if you know. A time with a time zone.
- What you know, limited to what's confirmed. "Errors began after this afternoon's deploy" is a fact. "A bad deploy caused it" is a conclusion.
- What you're doing: "We're rolling back the deploy."
That's enough. A short, true update in five minutes is worth more than a complete one in forty.
What to leave out
These are the sentences that come back to bite.
- Guessed causes. Early theories are often wrong. Name a cause once it's confirmed.
- Fix times you can't keep. "Within the hour" turns into an apology at the 61st minute.
- Scope you haven't measured. "A small number of customers" is a claim. If you don't know, say what's affected instead.
- Reassurances nobody checked. "No data was lost" needs someone to have checked.
- Uptime figures from memory. If you quote a number, it should come from your records.
Later updates: change, not repetition
Post again when something changes: you've identified the problem, a fix is in place, you're watching it. Each update should say what's new. If nothing has changed for a while, say that too; silence reads as neglect.
The resolved update
Say it's resolved when it is, not when you hope it is. Then say what was done, in a sentence. If you know the cause, give it plainly; if you'll publish a fuller report, say so.
The post-incident report
A good report has a summary, a timeline from your records, what happened, the confirmed root cause, how it was resolved, and what you'll change. If a section isn't known yet, leave it marked as unknown rather than filling it in.
A simple rule for the whole incident
Write only what someone on the team has confirmed. Keep those facts in one place, so every update, email and post says the same thing. Have one person approve each update before it goes out.
That's the habit Vigila is built around: your team writes the facts, Vigila drafts the update and the email from those facts only, and a person approves it before it's published. You can try it on a sample incident, without an account, at app.vigila.new-odyssey.com/try.
Questions
How soon should the first incident update go out?
As soon as you've confirmed customers are affected. The first update doesn't need a cause or a fix; it needs what's affected, since when, and that you're working on it.
Should I give an estimated time to fix?
Only if your team is confident in it. A missed estimate costs more trust than no estimate. Say when you'll post the next update instead, and keep that promise.
When should I say what caused it?
Once the team has confirmed the cause, usually in the resolved update or the post-incident report. A guessed cause that turns out wrong is the most common way an update loses trust.