Explaining a Bug to a Client Who Doesn't Know What a Bug Is

Ask me to write a function and I'm fine. Ask me "tell me about a time you explained something technical to a non-technical person" and I used to freeze, then start listing every client meeting I've ever had, none of them in enough detail to actually count as an answer. So I picked one and wrote it out properly. This is that.

The question, and why it's actually hard

The behavioral version usually sounds like:

"Tell me about a time you had to explain a technical problem to someone non-technical."

It sounds soft. It isn't. What they're really checking is whether you can take something tangled and make it land for a person who can't follow the jargon, without making them feel stupid and without lying about what's actually broken. That's a real skill, and it's easy to fail on the spot with something vague like "I just explain it simply."

So here's the specific story I use, in STAR shape, because that's the format these answers get graded on.

Situation

I built a booking site for a client. Small business, no in-house tech person. Everything worked in testing. Then two days after launch she emails me: some customers are getting charged twice, and one of them had already called her, annoyed.

She's not asking me "what's the race condition." She doesn't know that phrase. She's asking "is my site broken, and are you going to fix it."

Task

Two things at once, really:

• Fix the actual bug
• Before that, explain what was happening in a way she understood, that didn't panic her more than she already was, and that stayed honest, because part of it was my mistake

Action

First thing I did was not talk about code at all. I told her:

"When someone clicks Pay and the internet hiccups, the site doesn't hear back in time, assumes it failed, and lets them try again. Sometimes both tries actually go through."

That's it. No "idempotency," no "duplicate POST request." Just the shape of the problem, in words she could repeat to her own customer.

Then I told her what it meant for her, concretely: probably three or four affected bookings, here's how we find them, I'll refund the doubles today, and the permanent fix takes about a day.

Then, and this part mattered, I said plainly that the retry-safety check was something I should have built in from the start. Not groveling. Just naming it.

The fix

Small, once the explaining was done. Every payment attempt carries a unique key, and the payment side ignores a key it has already seen:

async function charge(bookingId, amount, idempotencyKey) {
  if (await alreadyProcessed(idempotencyKey)) {
    return getExistingResult(idempotencyKey);
  }
  const result = await paymentProvider.charge(amount);
  await save(idempotencyKey, result);
  return result;
}

The code was the easy half. The explaining was the hard half.

Result

She refunded the affected customers the same day using the list I sent, and the double charge stopped. She stayed a client for two more projects after that.

The thing she said later that stuck with me: she'd finally understood what was going on. Previous developers had always made her feel like she wasn't allowed to ask.

What this actually demonstrates

If you're prepping this question, don't just tell the story flat. Say what each part shows:

• Translating without dumbing down: the "internet hiccup" explanation is accurate, it's just not wearing a suit
• Owning a mistake in front of a client without torching their confidence in you
• Handing over the right information: she knew exactly what to do next, find bookings and issue refunds
• Separating here's the problem from here's the timeline so she wasn't waiting on one to hear the other

Quick recap

• The question is really "can you make a hard thing land for someone who can't follow the terms, and stay honest doing it?"
• Pick one real story and prep it in STAR shape, don't improvise across ten half-stories
• Explain the problem as a sequence of plain events, not a named concept
• Tell them what it means for them, and what you need from them, separately from the technical fix
• If it was partly your fault, say so in one sentence and keep moving

Honestly, the reason this one works as an interview answer is that it's true, and I've told the plain version enough times that it doesn't come out sounding rehearsed. That's the whole point of writing it down once.