In this guide
Engineers explain systems to non-engineers all the time: a product manager asks why a feature will take six weeks, a support lead asks why some customers see stale data, an executive asks whether the outage could happen again. These conversations often go badly in a familiar way. The engineer starts with how the system works, the listener nods politely, and ten minutes later neither side knows what was decided.
The problem is rarely that the listener cannot understand. It is that the explanation answers a question they did not ask. A PM does not need to know how the cache invalidation works; they need to know which customers are affected and what it costs to fix. This guide covers a method for explaining systems to people who do not read code: start from their decision, choose the right level of detail, pick diagrams and analogies that hold up, and translate technical risk into terms they can act on.
Key takeaways
- Start from the decision the listener needs to make, and work backward to the minimum explanation that supports it.
- Lead with the answer, then the reason, then the detail. Stop as soon as they have enough.
- Use one simple diagram of the user-visible flow, with the problem marked on it. Avoid architecture diagrams with every service.
- Choose analogies that match the specific property you are explaining, and say where the analogy breaks.
- Translate risk into likelihood, impact and options with costs. Never just say "it's complicated".
- Check understanding by asking them to restate the decision, not the technology.
Start from their decision
Before explaining anything, figure out what the listener will do with the answer. Different audiences have different decisions.
| Audience | Typical question | Decision behind it |
|---|---|---|
| Product manager | Why will this take six weeks? | Cut scope, change the date, or accept it |
| Executive | Could this outage happen again? | Fund the fix, accept the risk, or communicate to customers |
| Support | Why do some customers see old data? | What to tell customers, when to escalate |
| Sales | Can we support this customer's integration? | Whether to commit, and what to promise |
| Legal or compliance | Where does customer data go? | Whether the system meets an obligation |
If you are not sure what the decision is, ask. "What will you do with this?" is a fair question, and the answer will shorten the explanation by half.
Lead with the answer
Structure every explanation the same way: answer, reason, detail. Most technical explanations go the other way, building up from fundamentals to a conclusion. That works for engineers reading a design doc. It does not work for a busy listener who might stop paying attention after two minutes.
Compare two versions of the same explanation to a PM.
Bottom-up:
So the way the export works is that we have a worker that pulls jobs off a queue, and each job queries the reporting database, which is a replica of the main one. The replica can lag behind, sometimes by several minutes under load, and the export doesn't check for that, so...
Answer first:
Exports can be up to a few minutes out of date during busy periods. It affects anyone who exports right after making changes. We can fix it two ways: a quick fix in about three days that makes exports slower, or a proper fix in about two weeks that keeps them fast. I'd recommend the quick fix now and the proper one next quarter.
The second version gives the PM everything they need in four sentences. If they want to know why, they will ask, and you can go one level deeper.
Choose the right level of detail
Think of detail as layers. Go down one layer only when the listener asks or when the decision depends on it.
- Outcome: what the user experiences. "Exports can be a few minutes stale."
- Mechanism: the one concept that explains it. "Exports read from a copy of the database that updates slightly behind the original."
- Components: the parts involved. "The export worker, the reporting replica and the queue."
- Code: specific functions and files.
Most non-engineering conversations should stay at layers 1 and 2. Layer 3 is appropriate for technical PMs or when discussing cost. Layer 4 almost never helps.
Use one diagram of the user-visible flow
A diagram is often the fastest way to get shared understanding, but the wrong diagram makes things worse. Architecture diagrams with every service and database are for engineers. For non-engineers, draw the path of one user action, using names they recognize, and mark where the problem is.
[Customer edits a record] --> [Main database] ..copies every few seconds (minutes when busy)..> [Reporting copy] --> [Export file]
^^^ the delay lives here
Good diagrams for this audience:
- Have five to seven boxes at most.
- Use product language ("customer edits a record") instead of service names ("orders-api").
- Show one flow, left to right.
- Mark the problem or change with a single highlight.
- Fit on one slide or one screen without zooming.
If you need to show the broader system, use a context-level view: the product, the users, and the external systems it talks to. The C4 model's system context diagram is designed for exactly this audience, and the comparison of C4 and generated architecture maps covers when each fits.
Pick analogies that hold up
A good analogy maps one specific property of the system onto something familiar. A bad analogy maps the whole system and breaks as soon as anyone asks a follow-up question.
| Concept | Analogy | Property it explains | Where it breaks |
|---|---|---|---|
| Replica lag | A shared document that syncs to your laptop every few minutes | Reading slightly old data | Real replicas usually catch up in seconds |
| Queue | A ticket line at a deli counter | Work waits its turn; more counters means faster service | Queues can reorder or retry |
| Cache | A sticky note with an answer you looked up earlier | Fast, but may be out of date | Caches have explicit expiry rules |
| Technical debt | Deferred maintenance on a building | Small costs now avoid big costs later, but they compound | Debt is not evenly spread |
| Rate limit | A store that only lets so many people in at once | Protecting the system from overload | Limits are per customer, not global |
Say where the analogy breaks if the decision depends on that part. "It's like a deli line, except that if the person at the counter fails, they go back to the end of the line and try again" is still simple and much more accurate.
Translate risk into decisions
Non-engineers often hear risk as either "it's fine" or "everything is on fire", because engineers tend to describe risk in technical terms without likelihood or impact. Use a consistent shape:
- What could happen, in user terms.
- How likely, in plain words with a reason. "Unlikely; it requires two specific failures at the same time" or "It happened twice last quarter."
- How bad, in user or business terms. "Customers in one region can't log in for up to an hour."
- Options, each with cost and effect.
- Your recommendation.
A short template for writing this down:
Risk: Exports can return stale data during peak hours.
Who is affected: Customers who export within a few minutes of editing.
How often: Several support tickets per month, mostly from finance users at month end.
Impact: Wrong numbers in reports; customers lose trust in exports.
Options:
A. Read exports from the main database. 3 days. Exports get slower for large accounts.
B. Wait for the copy to catch up before exporting. 2 weeks. No slowdown.
C. Show a "data as of" timestamp. 1 day. Doesn't fix it, but sets expectations.
Recommendation: C now, B next quarter.
Be honest about uncertainty. "I'm not sure yet; I'll know by Thursday after we check the logs" is far more useful than a confident guess that turns out wrong.
Explaining estimates
"Why will this take six weeks?" is the most common version of this conversation. Avoid defending the estimate with complexity. Instead, break it into parts that map to things the listener can see, and point out which parts are negotiable.
- "About two weeks is the feature itself."
- "About two weeks is changing how permissions work, because today only admins can do this, and that touches every screen."
- "About a week is migrating existing customer data safely."
- "About a week is testing with the three largest customers, who use it differently."
Now the PM can make choices: ship to non-admins later, skip the migration for new accounts only, or test with one large customer instead of three. You have turned a number into a conversation about scope.
Check understanding the right way
Do not ask "does that make sense?" Everyone says yes. Ask them to restate the decision: "So, to check we're aligned, what are you going to tell the customer?" or "Which option are we going with?" If their answer is wrong, the explanation was not clear, and you can adjust.
Follow up in writing, especially for decisions with consequences. A short message with the answer, the options and what was decided becomes a reference everyone can point to.
Building explanations faster
Much of the work of explaining a system is getting your own picture straight first, particularly in areas you do not own. A clear explanation of a flow you only half understand is impossible. Tools that trace a flow for you help here. In OpenVisio, Ask answers a direct question about a repository with a numbered process and a flowchart for the relevant section, which is a useful starting point for a non-technical explanation once you have checked it against the code. The Tour also has a slides view, which can be a quick way to walk a technical PM through how a product area fits together.
The craft, though, is in the translation: their decision first, the answer before the reason, one diagram of the user-visible flow, an analogy that holds up, and risk stated as options. That works whether you have a tool or a whiteboard.
