Most incident write-ups are written for engineers: a timeline, a root cause, a list of tickets. The person who actually reads the email after a client's checkout was down for 40 minutes is usually not an engineer. It's an operations manager who has to explain it to their boss before lunch.

This post is the template I'd use for that email, plus the part that usually goes wrong: the second incident, weeks later, when nobody remembers what the client asked for the first time. (Disclosure: I build Maildoer, an email-based assistant, and I'll mention where it fits once near the end. The template works without it.)

The scenario below is a labelled hypothetical, not a customer story.

Say you're the on-call developer at a small agency

You maintain an online shop for a client in Germany. On a Tuesday evening, payments fail for a while. You fix it, and your notes look like this:

19:02 alerts: checkout 5xx 19:10 payment webhook timing out, provider status page green 19:24 rolled back yesterday's deploy, errors continue 19:31 found expired credential for webhook signing 19:42 rotated credential, checkout recovered 19:50 ~30 orders failed, customers saw "payment error"

Accurate, and useless to the client's ops manager.

The five-part summary

Here's the structure I'd use for anything a non-engineer reads:

  1. What customers saw. One sentence, in their language: "Between 19:02 and 19:42, some customers saw a payment error at checkout."
  2. Impact in numbers you can stand behind. "About 30 orders did not complete." If you're not sure, say "about" and say how you'll confirm.
  3. What we did. Two sentences, no jargon. "A security credential used to confirm payments had expired. We replaced it and checkout recovered."
  4. What changes now. Concrete, owned, dated. "We've added a reminder 30 days before this credential expires (owner: us, done)."
  5. What we need from you. Often the most useful line: "Would you like us to email the affected customers, or will your team?"

What to leave out: blame, the rollback that didn't help, internal tool names, and anything you'd have to retract later.

The first email from the client

The next morning the ops manager replies with house rules. Paraphrased:

Thanks. For future incidents: - Always give times in Berlin time, not UTC. - Don't name our payment provider in anything we might forward. - I need a German version for the warehouse team. - Put "what we need from you" at the very top.

You follow all four rules. Everyone is happy.

The second incident, five weeks later

A different engineer is on call. A shipping-label integration fails for an hour. The ops manager's whole email is:

Labels down again this morning? Same as last time please.

"Same as last time" carries all four rules. If whoever writes the summary only sees today's message, you get UTC times, the provider named in the second paragraph, English only, and the ask buried at the end. The facts are right and the email still fails, because it ignores what the client already told you.

This is the failure I find most interesting: the latest email is short because the earlier ones were long.

A checklist that survives on-call rotation

If you don't have anything that remembers for you, write the rules down where the next person will look:

  • Keep a per-client "comms rules" block at the top of the incident template: time zone, names to avoid, languages, order of sections.
  • Link the previous summary in the new incident ticket, not just the previous root cause.
  • Diff your draft against the last one before sending. If the structure changed and nobody asked for it, that's probably a regression.
  • Write the German (or any) version from the facts, not as a word-for-word copy of the English: warehouse staff need "which labels to reprint", not the executive framing.
  • Re-read the client's last reply to you before you hit send. Corrections live there.

Where Maildoer fits

Maildoer is the tool I build: you email a task with attachments to do@maildoer.com and get back a summary, a translation, a reply draft or a report. The part relevant here is that a later email from the same person is read together with their earlier ones. So "Same as last time please" plus today's notes can be handled with the Berlin times, the unnamed provider, the German version and the ask at the top, without pasting the rules in again. You can also reply to the result ("shorter, and add the reprint count") instead of starting over.

It doesn't replace the checklist above. The written rules block still matters, because your teammates need it too.

What I'd do differently

If I were setting this up again, I'd ask for the house rules before the first incident, in the kickoff email: "When something breaks, what time zone, which languages, and who forwards our emails to whom?" Clients answer that happily when nothing is on fire.

How does your team keep per-client communication rules from getting lost between on-call shifts?

If you'd like to try it, each email address gets 100 credits on first use as a trial allowance: https://maildoer.com