Adyakshar Labs

Adyakshar Labs / Blog

Engineering Management

What "We Are Investigating" Really Means: Engineer-to-English for Incident Updates

Black desk lamp beside the title: What we are investigating really means

It is 2:40 on a Tuesday afternoon and the checkout page has stopped working. A manager opens the team channel and finds a single line from the engineer on call: "We are investigating."

The manager reads it three times. Is that good news? Is it bad news? Should the customer be called? Nobody can tell, and that is the problem. Incident updates are written in a dialect that engineers understand and almost nobody else does.

This is the fifth post in our Engineer-to-English series, where we translate the things engineers say into what they mean. This one is about the words we use when something is broken.

Four phrases, translated

A table of four incident phrases next to their plain-English meaning

"We are investigating." It is broken, and we do not yet know why. This is an honest sentence, and often the only true one available in the first ten minutes. The trouble is that it can sit in a channel for an hour and mean nothing more.

"A fix is being rolled out." We have a theory about the cause, and we are testing it in front of you. This one is useful only if it says how long a rollout takes and how we will know it worked.

"Some users may be affected." Assume you are one of them. Teams use "some" and "may" because they do not yet know the size of the problem. Readers should hear that as "we are still counting", and writers should say so.

"Root cause analysis to follow." Ask again after everyone has slept. It is a fair promise and a good practice, but it needs a date. Without one it quietly becomes never.

Why teams talk this way

None of these phrases is dishonest. Under pressure, engineers avoid saying anything they might have to take back. If you announce a cause and it turns out to be wrong, you have made the incident longer and your credibility shorter. So people reach for words that are safe: vague, passive and a little formal.

The cost is paid by everyone else. A customer wants to know whether to wait or to use another route. A salesperson wants to know whether to warn a client. A manager wants to know whether to wake someone up. Safe words answer none of those questions.

There is a better approach, and it does not require pretending to know more than you do. It requires saying plainly what you do not know.

What the reader actually needs

Think of the people reading an update as asking four silent questions.

  1. What is going on?
  2. How bad is it for me?
  3. What are you doing about it?
  4. When will I hear more?

Most incident updates answer the first question vaguely, skip the second, hint at the third and ignore the fourth. The fourth matters most. A person who knows when the next update is due can stop refreshing the page and get on with their afternoon. A person who does not know will keep asking, and every question interrupts the people trying to fix the problem.

A better update has four lines

Four numbered lines: what we know, what we do not know, what we are doing next, when you will hear from us again

The format is deliberately plain.

  1. What we know. Only facts that have been checked. "Card payments are failing at checkout. Browsing and login are working."
  2. What we do not know. Say it out loud. "We do not yet know the cause or how many customers are affected."
  3. What we are doing next. One action, with an owner. "Priya is checking the payment provider's status and our last deployment."
  4. When you will hear from us again. A time, not a promise. "Next update at 3:15, or sooner if something changes."

Notice that the second line is the one that feels uncomfortable to write, and it is the one that builds the most trust. Readers forgive a problem. They are much less forgiving of a feeling that someone is hiding it.

Try it on the update above

Here is "We are investigating" rewritten.

"Card payments are failing at checkout since about 2:30. Browsing and login are working. We do not yet know the cause or how many customers are affected. Priya is checking the payment provider and our last deployment. Next update at 3:15."

It is six sentences instead of four words. A manager can act on it, a support agent can answer a customer with it, and the engineer can paste the same text again with one line changed at 3:15.

Habits that make this easier

A few small habits help a team get there.

  • Write a template before you need it. Nobody drafts good prose in the middle of an outage. Keep the four lines in a pinned message and fill them in.
  • Name one person to write updates. The person fixing the problem should not also be the person explaining it. Splitting the roles shortens the incident.
  • Set the next update time every time. Even "no change, next update at 4:00" is useful. Silence is not.
  • Hold the root cause review, and give it a date. "Root cause analysis to follow" is only a promise if the follow-up is on a calendar.
  • Say what customers should do. If the right advice is to wait, say so. If it is to use another route, say that.

The point of all this

Engineer-to-English is not about making engineers sound less technical. The technical detail still belongs in the incident log, where it is useful. It is about making sure the people who depend on your system are not left guessing while you work.

A good incident update is a small act of respect for the reader's time. It says what is known, admits what is not, names who is working and promises a next step. That is rarely more than a few sentences, and it is worth practising before you need it.

Which of these phrases do you hear most in your own incident channel? We would like to know what you would add to the list.

  • incident response
  • communication
  • engineering management
  • software engineering
  • adyakshar labs

Keep reading

Engineering Management · 4 min read

The Small Change That Was Not Small

Every team has heard "it's just a small change." Here is what that sentence usually means, why it keeps costing money, and three questions that make a small change honestly small.

From across the family

More reading from the other Adyakshar Labs products.

Bindus
How Long Did That Job Really Take? Using Time Sheets and Milestones HonestlyMost small teams quote from memory and learn the real number after the job is done. A simple habit with time sheets and milestones makes the next quote better than the last.
Sampad AI
What to Do in the First Two Days After a Tax Notice ArrivesA tax notice rarely gets worse in two days. It gets worse when it sits. A short checklist for capturing the facts, updating the client and planning the reply.
Quantum Labs
Harvest Now, Decrypt Later: How to Decide What to Protect FirstEncrypted data can be recorded today and read later. You cannot protect everything at once, so sort it by shelf life. A plain test and a three-tier list for deciding what comes first.