Explaining Technical Concepts to Non-Technical Audiences Questions

Direct answer

An API is a set of rules that lets two pieces of software ask each other for things and get a response back, the same way a restaurant menu lets you ask the kitchen for a specific dish without needing to know how it's cooked. For support, the practical version is: our product and some other company's system talk to each other automatically over the internet, in a fixed, agreed format, and when that conversation fails, it looks like "the app is broken" even though our code and their code may both be working correctly on their own.

Walking through the request/response flow, and what to leave out

• Client asks, server answers. Frame every API call as one system asking a narrow question ("what is this customer's order status?") and the other giving a narrow answer. Don't teach REST verbs or endpoint names to a support audience, they need the shape of the interaction, not the vocabulary.
• Name the four things that can go wrong, because that's what a support rep actually needs on the spot: the question was asked wrong (a bug on our side), the other system refused to answer (their outage, or our access was revoked), the answer came back garbled or incomplete (a partial failure), or the answer took too long and we gave up waiting (a timeout). Mapping a customer's symptom to one of these four buckets is the real skill being taught here, not the word "API" itself.
• Decide what to omit on purpose: authentication and rate limits are real and matter to engineers, but for a support rep they collapse into one sentence, sometimes the connection itself needs permission or is being used too much, and that shows up looking like the same kind of failure as an outage. Don't walk through how tokens work, it adds vocabulary without adding troubleshooting power.
• Check understanding with a real ticket, not a definition. Hand them a recent "the button doesn't do anything" ticket and ask which of the four failure buckets it fits.

Worked example

Say a customer reports our order-status page came back empty. Behind the scenes, when they loaded that page, our app sent a request to our shipping partner's system asking, in effect, "what's the status of order 48213?" Two things can happen: the shipping partner answers with the status and our page displays it, or something breaks in that exchange, their system is down, our request had a typo, or the token proving we're allowed to ask has expired, and our page has nothing to show, so it renders blank instead of an error message. For the support rep, the API is the reason "our website" and "the shipping company's website" can disagree at the exact same moment: they're two separate systems, and this blank page is what it looks like when the conversation between them fails partway through, not when either system is fundamentally broken.

Trade-offs and pitfalls

The waiter analogy earns its keep for the request/response shape, but it breaks down the moment a rep asks "so can I just call them and ask directly?", real APIs are automated, high-volume, and machine-to-machine, there's no waiter to flag down. Say that limit out loud rather than let them assume a human process exists behind it. The bigger pitfall is oversimplifying past the point of being useful: a support rep who can only say "it's an API problem" can't triage a ticket. The four-bucket failure model above is close to the minimum depth that turns the definition into something actionable, cut much further and the explanation stays clear but becomes useless.

Direct answer

The core move in an incident explanation to a non-technical audience is separating three layers up front: what happened (in plain terms, no root-cause mechanism), what it meant for them (impact, in terms they already track), and what's being done about it, then deliberately leaving out anything that doesn't serve one of those three. Below is an incident where I did that under time pressure, including delivering it live to a mixed engineering-and-business audience.

What to include, what to leave out, and how to decide

• Lead with impact, not sequence. Legal, sales, and executives care about what happened TO THEM first, which customers, how long, what's the exposure, the technical timeline is useful evidence, not the headline.
• Deliberately exclude logs, stack traces, and internal service names; they add authority for an engineering audience and add nothing but confusion for this one. A useful test: if a detail doesn't change what the listener should do next, leave it out.
• Give the cause in one plain sentence with no jargon, something like "a recent configuration change made one of our systems too slow to respond to a partner service in time," rather than either omitting cause entirely (which reads as evasive) or over-explaining the mechanism.
• When delivering this live rather than in a written report, whether it's a hallway update or presenting a postmortem verbally to a room that mixes engineers and business stakeholders, pause after the impact statement for questions before moving to cause. People worried about impact can't absorb a root-cause explanation until that worry is addressed first.

Worked example

Situation: during a high-traffic sales period, our payment service began intermittently failing checkout requests for roughly ninety minutes. Legal, sales leadership, and the executive team needed an explanation quickly.

Task: explain what happened clearly enough for them to act, communicate with affected customers, assess any obligations, decide on immediate next steps, without either alarming them with irrelevant detail or minimizing the impact.

Action: I opened with impact, in the terms they track: which customers were affected, for roughly how long, and that the issue was fully resolved and being watched closely. I gave the cause in one sentence: a recent configuration change made our payment service too slow to respond to our external payment gateway in time, causing some checkout attempts to fail. I described what we did in plain terms (reverted the change, increased how long we wait before giving up on a slow response, added an automatic circuit breaker so a slow dependency can't cascade into a wider outage) and what we were doing next (a deeper review, with a fuller technical writeup available to anyone who wanted it). I left out the specific error codes, service names, and configuration parameter, none of which changed what legal, sales, or the executives needed to do next. I paused for questions right after the impact statement, before moving on, and answered a legal question about customer notification obligations directly instead of routing it back to engineering jargon.

Result: legal and sales left with a clear, accurate picture of exposure and could communicate confidently with affected customers; the executive team approved the follow-up work (the circuit breaker and review) without needing to dig into implementation detail themselves, and a fuller technical postmortem was made available separately for the engineering team that wanted the mechanism-level explanation. I learned that pausing for questions right after the impact statement, before cause, kept people from tuning out a cause explanation they weren't ready to hear yet.

Trade-offs and pitfalls

Leaving out technical detail can read as evasive if you do it silently; I said "I'm not going to walk through the technical internals here, I'm glad to share those separately" so the omission was visible on purpose rather than hidden. The other pitfall is understating severity to keep the room calm, that erodes trust the moment the real scope becomes clear later. State the honest impact even when it's uncomfortable, and let the "what we're doing about it" section carry the reassurance instead of the impact statement itself.

Direct answer

Separate the technical cause from the customer-visible effect, and only translate the effect: what customers experienced, what's being done, and when they'll hear next. If any detail has to be withheld for legal or security reasons, say so explicitly rather than leaving a silent, unexplained gap.

Structured elaboration

Five rules for turning a jargon-filled draft into something a customer can use:

1. Start with user impact in plain language. Who is affected and how, described in terms the customer would use themselves, not the terms engineering used to diagnose it.
2. Name the current action and who owns it, so customers know it's actively being worked, without needing to understand what the action technically involves.
3. Give a clear next step or ETA, and be explicit about what customers should or should not do; update the ETA if it changes rather than let it quietly expire.
4. Use short sentences and active voice. If a technical term is genuinely necessary, define it in the same sentence, not in a glossary customers won't read.
5. Close the loop: state you're actively monitoring and commit to a specific next-update time or condition.

Format variants of the same discipline. A status page compresses this to two or three sentences, updated as the situation changes. A public FAQ breaks the same content into the questions customers are actually asking (what happened, am I affected, what should I do, when will it be fixed). A security-sensitive incident needs one more move: state the impact and remediation fully, but withhold exploit mechanics, and say so plainly rather than leave the omission unexplained, for example, "we're not sharing full technical detail while we confirm the fix is complete, to avoid giving that information to anyone trying to exploit it further."

Worked example

Original draft (too much jargon): "A regression introduced in the v2.14 deploy caused cache-invalidation storms, exhausting database connection-pool headroom and resulting in elevated P99 latency and 5xx error rates on write-path endpoints for roughly 12% of traffic."

Rewritten for customers: "Some customers are experiencing delays and failures when saving changes in the app, and may see error messages or slow pages. Our engineering team is actively rolling back a recent deployment and restarting the affected services to restore normal operation. You don't need to take any action; any in-progress work should be preserved, but please save again once you see things recover. We expect most customers to see improvement within the next 45 minutes, and we'll post another update when the fix is complete or if that timeline changes. We're sorry for the disruption and are monitoring the system until it's fully resolved."

Trade-offs & pitfalls

Over-reassuring language ("everything's fine!") backfires if the problem is still visible when the customer reads it, credibility drops faster than if you'd stated the impact plainly. Adding technical detail "for transparency" often confuses more than it reassures, transparency is about honesty of impact and timeline, not about proving you understand the root cause. The redaction tension is the sharpest pitfall: being vague to protect security is legitimate, being vague to avoid admitting fault is not, and the difference to the reader is whether you say you're being deliberately non-specific or just leave a gap that reads as evasive.

Direct answer

Running two active data centres means duplicating the infrastructure that serves users, so if one site fails, the other keeps serving with little to no interruption. That duplication raises fixed costs (hardware, networking, and the ongoing work of keeping both sites synchronized and tested), in exchange for far less user-visible downtime, because a failure that would take a single-site setup fully offline gets absorbed by the second site instead.

Structured elaboration

• Define the trade-off in plain terms first, before any numbers: it is duplicated cost bought to avoid duplicated failure. "Availability" here just means the percentage of the year the service was actually reachable.
• Make the trade-off concrete with a numeric example (below), because "increases cost but reduces downtime" is true of almost any resilience investment and doesn't help leadership decide if this specific one is worth it.
• Note diminishing returns. Going from a single site to two active sites buys a large downtime reduction for a moderate cost increase. Pushing further, from four nines to five nines, typically costs disproportionately more for a much smaller absolute gain, so the decision should track business impact per minute, not availability percentage for its own sake.
• Two format variants worth knowing. The same numeric framing works as a short memo to executives requesting an SLO increase: state the change and its downtime-and-dollar consequence in the first two sentences, then put the derivation below as supporting detail. It also works, largely unchanged, when the audience is an external client evaluating your reliability commitments rather than internal leadership, the difference is that you're now translating into an SLA commitment they can hold you to, not just an internal budget ask.

Worked example

Say a single data centre gets the service to 99.9% availability. A year has 525,600 minutes, so the downtime is 525,600 x (1 - 0.999) = 526 minutes a year (about 8.75 hours), at a cost of $1.0M a year.

A second active site raises availability to 99.99%: 525,600 x (1 - 0.9999) = 53 minutes a year, at a cost of $1.6M a year.

That's 526 - 53 = 473 minutes of downtime avoided for an extra $600k a year, or about $1,270 for every minute of downtime avoided (600,000 / 473 ≈ 1,270). Leadership can weigh that against what a minute of downtime actually costs the business (lost revenue, support load, customer trust) to judge if the trade is worth it.

When business and engineering are in the same room (a consistency-model version of this same trade-off), layer the explanation instead of picking one level: open with the plain-language framing everyone can hold ("does an update show up everywhere instantly, or does it catch up a moment later"), then, once that lands, add one sentence naming the actual mechanism for the engineers in the room, eventual consistency versus strong consistency, so nobody is bored or lost at the same time.

Trade-offs & pitfalls

The cost-per-minute figure is a useful summary, but it's a simplification: not all minutes cost the same (an outage during checkout hours costs far more than one at 3am), and the model should say so rather than imply a flat rate. A second pitfall: two data centres do not eliminate all downtime, correlated failures (a bad config pushed to both sites, a shared upstream dependency) can take both down together, so "two sites" is risk reduction, not risk elimination, and that caveat belongs in the leadership conversation, not just the postmortem.

Direct answer

The number doesn't change across audiences, but what it's evidence for does: to a CEO it's a business outcome (conversion, retention, cost), to external developers it's a reliability guarantee they can build on, to internal engineering managers it's a load and capacity signal. Same 30% improvement, three different "so what," each with the one metric that audience should actually track next.

Structured elaboration

The technique is picking, per audience, which consequence of the number they actually own:

1. Translate the metric into the currency that audience is measured on before stating it. A CEO is measured on revenue and retention; an external developer is measured on their own app's reliability; an internal engineering manager is measured on system load and incident risk.
2. Give exactly one metric to track next, not a dashboard's worth. Too many numbers reads as "we're not sure which one matters"; one number reads as a clear owner and a clear signal.
3. State the baseline and direction explicitly, down from 500ms to 350ms, not just "faster," so nobody has to ask what the improvement actually was.
   This same three-move pattern is what you would reuse for a different metric to the same or different audiences: messaging a lazy-loading improvement to executives, sales, and developers, an API deprecation to engineering, customers, and executives, or a throughput doubling to a CTO, operations, and sales. The technique is constant; only which consequence you lead with changes per audience.

Worked example

p95 latency means the response time that 95% of requests are faster than, so it's a measure of how slow the worst-but-common cases are, not the average case.

To the CEO: "We cut the time it takes customers to sign in from half a second to a third of a second, 500ms to 350ms, a 30% improvement, on the slowest 5% of requests, the ones customers actually notice as lag. Faster sign-in means fewer people abandoning at login and less friction on every visit. Metric to track: conversion rate on the sign-up-to-first-action flow over the next two weeks, to see if that translates into fewer drop-offs."

To external developer customers: "Our authentication endpoint's p95 latency, the response time 95% of your calls beat, dropped from 500ms to 350ms. You should see fewer client-side timeouts and retries against this endpoint. Metric to track: your own timeout and retry rate against our auth endpoint, it should trend down."

To internal engineering managers: "We cut auth p95 from 500ms to 350ms through caching and query tuning, which lowers tail latency for every downstream service that calls auth before doing its own work. Metric to track: queue length and tail latency on the services immediately downstream of auth, to confirm the improvement is propagating rather than just moving the bottleneck."

Trade-offs and pitfalls

Reusing the same "30% faster" framing for every audience without a metric attached invites the follow-up "compared to what, and how would I know it's working," which is exactly what the per-audience metric answers in advance. It's also a mistake to promise a business outcome, like "this will increase conversion," as a fact rather than a hypothesis. Latency and conversion correlate but aren't guaranteed to move together for every product, so the honest version says "we would expect to see," not "this will." And if a later measurement shows a segment of customers saw no improvement, say a region or client version, that needs its own honest message rather than folding it quietly into the aggregate number.