How to explain a bug in English, to developers and to managers

To explain a bug clearly in English, say four things in this order: what happens, what should happen, when it happens, and what you know about the cause. The same four parts work for a developer, a manager and a client. Only the level of detail changes.

Most non-native speakers know the technical words. What goes wrong is the order: they start with the stack trace and the listener is lost before the point.

The four parts

1. What happens: "Users can't log in with single sign-on."
2. What should happen: "They should be redirected to the dashboard."
3. When it happens: "Only on Safari, since yesterday's release."
4. What you know: "It looks like the redirect URL is missing a parameter. I'm checking the auth config now."

If you can only say one sentence, say the first one. Everything else is detail.

To a developer

Developers want reproduction steps and your current hypothesis.

The export job fails for accounts with more than 10,000 orders. It times out after 30 seconds. I can reproduce it locally with the seed data. My guess is the query does a full table scan, because the index on created_at is missing. I'm going to add the index and check the query plan.

I can reproduce it locally.Shows the bug is real and you can test a fix. My guess is… but I haven't confirmed it yet.Hypothesis, clearly labelled as one. It only happens when…Narrows the conditions.

Explaining it step by step to a colleague, or even to an object on your desk, often reveals the cause on its own. Programmers have a name for this: rubber duck debugging (Wikipedia). Doing it in English doubles as speaking practice.

To a manager

Managers want impact, risk and a time estimate. Put the conclusion first. The military calls this "bottom line up front" (BLUF, Wikipedia), and it works just as well in a status meeting.

Short version: some customers can't download their reports since this morning. It affects about 5 percent of accounts. We know the cause and the fix is in review. It should be live by 3 p.m.

Short version:Signals that the detail will come only if they ask. It affects about … of users.Impact in numbers. We have a workaround in the meantime.Reduces panic.

To a client

Clients want to know that you are on it and when it will be fixed. Avoid internal names and blame.

Thanks for reporting this. We've found the issue: in some cases the confirmation email wasn't sent after payment. Your payment went through correctly. We're releasing a fix today and will resend the missing emails.

When you don't know yet

Uncertainty is the hardest thing to say in a second language without sounding incompetent. These phrases help.

We don't know the cause yet. We're looking at two possibilities.Honest, but shows a plan. I'd rather not give an estimate until I've tested the fix.Polite refusal to guess. I'll update you by the end of the day either way.A commitment you can keep.

Practise the explanation, not just the fix

Explaining a bug under pressure is a speaking task, and it improves only by speaking. Pick a real bug from last month, explain it out loud to each of the three audiences, and notice where you start over-explaining. A voice tutor can play the impatient manager. In FluentSession you describe the tutor's role yourself, for example "an engineering manager who wants a short answer and a deadline".