How to write an outage message customers trust

An outage message has one job: tell people what is broken, who it affects, and when you will speak again. Send it before you know the cause. Nobody is waiting on your diagnosis, they are waiting to find out whether the problem is theirs or yours.

The instinct is to hold the message until you have something useful to say. That instinct costs more trust than the outage itself.

Send the first message before you understand anything

Post as soon as you are confident something is genuinely broken, even when the only thing you can say is that it is broken.

The gap between the failure and your first word is the expensive part. People fill silence with explanations, and none of them are flattering. They reload. They blame their own setup. They ask a colleague whether your thing is always like this, and the colleague remembers the answer for a long time.

I make Unvent, and it leans on a backend. Long before that backend ever missed a beat, the failure had a sentence waiting for it: rewrites are paused right now, your draft is untouched. Two facts, no cause, no apology.

That sentence is still not enough. A line inside a product cannot say how long, and how long is the only thing anybody wants. If nothing else of ours is talking, the reader fills that in themselves, and what they land on is that the thing is flaky.

The first message can be three lines. Something is down, here is what it stops you doing, we are on it, next update at a named time. You can write that faster than you can finish deciding whether to write it.

Say what broke in the reader's words

Describe the outage by what the customer cannot do, not by which piece of your system fell over.

"The queue worker is backed up" tells your on-call engineer everything and your customer nothing. "Rewrites are not coming back" tells them whether to keep waiting or go do something else. That is the only decision they are trying to make.

Give them the shape of it:

• Name the action that fails, using the words that appear in your own interface.
• Say who is hit, whether that is everyone or only people doing one specific thing.
• Say what still works, because half broken looks fully broken from outside.
• Leave out component names unless your readers operate those components themselves.

The last one has an exception. If you sell to engineers, they want the internals, and hiding them reads as evasion. Everyone else hears jargon and translates it as "we are hoping you go away".

Promise the next update, not the fix

Commit to a time you will post again, and never to a time it will be working.

A fix time is a guess about a problem you have not finished understanding. Miss it and you have converted a technical failure into a credibility failure, which lasts considerably longer. Say "back in thirty minutes", miss it twice, and people stop reading your updates at exactly the moment your updates start mattering.

An update time is a promise you control completely. You can always publish a sentence. So publish one, on the clock, even when nothing has changed.

I think the update that contains no news is the most valuable message in the whole incident. "Still down, no new information, next update by quarter past" tells people you are awake, working, and not managing them. Skip it and everyone assumes you went home.

What to write when you still do not know

When you have no cause, write what you have ruled out and what you are doing right now.

"We are looking into it" is wallpaper. It appears in every incident ever posted and carries no information. "We reverted this morning's change and are watching sign-ins" is a fact, and it survives being read by someone in a bad mood.

Keep theories out of it. The half-formed guess your team is chasing in a private channel is fine there and dangerous in public, because whatever you name gets quoted back to you as your official position. State actions, not hypotheses. Actions are true when you write them.

Writing plainly at the exact moment you least want to write is a real skill, and mine deserts me under pressure like everyone else's. Taking the Direct rewrite in Unvent strips the flinching out of a sentence I did not want to have to write. Same facts, less wobble.

Words that make an outage worse

Certain phrases read as evasion even when you did not mean them that way, and readers are very good at spotting them.

• "Some users may be experiencing issues" when you already know it is everyone.
• "Degraded performance" when the thing does not work at all.
• "We apologize for any inconvenience" as the whole content of a message.
• Passive constructions that delete you from your own outage, like "an error occurred".
• Any hint that the reader's setup might be at fault when you know perfectly well it is not.

All of that language exists to protect you from the handful of people who might screenshot the message later. It does so by costing you the trust of everyone reading it now. Pick the crowd in front of you.

Apologies are worth their own note. Skip it in the first message, because an apology before facts reads as a substitute for facts. Put it in the closing message, once, in plain words, and let it sit next to a description of what actually happened. This is the same discipline that makes bad news at work land: the thing itself first, the feelings about it second.

The message after it is over

The closing message says it is working again and tells anyone still stuck how to reach you. One plain sentence about the cause belongs in there too.

That last part gets forgotten constantly. General fixes leave individual stragglers, with a stale session or a queued job that never cleared, and those people will assume the outage is ongoing while your status page says all clear. Invite them to tell you. Make it one reply, not a form.

The longer write-up is a separate document and it can wait. Most of your customers will never open it, and that is fine, because it is not written for them. It is read by the small group deciding whether to trust you with something bigger, and they are checking whether the story matches the updates you posted while it was still on fire.

Leave the old incidents up. A history of outages handled cleanly is a stronger sales document than a page that has never admitted to anything.

None of this makes the failure smaller. It decides what people think you are like under pressure, and that is what stays with them long after they have forgotten what actually broke. Which is irritating, because the fix was the part that took real work.