When something breaks, people stop reading code and start reading your messages. Managers, support colleagues and customers want to know three things: what is affected, what you are doing, and when they will hear more. A clear update in simple English does more for trust than a perfect fix delivered in silence.
What every update needs
- Status: investigating, identified, monitoring or resolved.
- Impact: who or what is affected, in plain words.
- What we're doing: one or two sentences.
- Next update: a time, even if nothing changes.
A template you can copy
[Status] [Service] – [short description]
Impact: [who/what is affected since when]
Current action: [what the team is doing]
Next update: [time and time zone]
Examples for each stage
Investigating: "We're investigating errors on checkout. Since 09:40 UTC, about 15 % of payments are failing. Orders that already went through are not affected. Next update by 10:30 UTC."
Identified: "We've identified the cause: a configuration change to the payment gateway. We're rolling it back now. Next update by 11:00 UTC."
Monitoring: "The rollback is complete and the error rate is back to normal. We're monitoring for the next hour before we close the incident."
Resolved: "Resolved. Between 09:40 and 10:52 UTC, some payments failed. Customers were not charged for failed payments. We'll share a postmortem by Friday."
Phrases that keep readers calm
- We're aware of the issue and are working on it.
- We've ruled out the database as the cause.
- There's no data loss.
- A workaround is available: …
- We'll update this thread every 30 minutes until it's resolved.
Common mistakes
- Jargon for the wrong reader. "The p99 on svc-auth spiked" means nothing to support. Say "logins are slow".
- Guessing the cause too early. Use "we think" or "we're checking whether" until you know.
- No next update time. Without it, people start asking in every channel.
- Blame. In updates and postmortems, describe what happened, not who did it.
Learn the whole set of work texts
Writing at Work for IT Teams B1–B2 has 24 chapters on the texts developers write every day, including incident updates, blameless postmortems, bug reports, code review comments and handover notes, with before-and-after examples, 15 templates and a "before you send" checklist. The words around the code (rollback, workaround, feature flag) are in IT Vocabulary in Real Life B1–B2.
