Start with why the listener should care. Then explain only enough mechanism to support the conclusion. End with the decision, trade-off or next action.
Goals
How to explain technical concepts to non-technical colleagues
Explain a technical problem, system or recommendation without dumping the architecture: start with the consequence, keep the necessary mechanism, and name the decision or next step.
A technical explanation fails when it is accurate but forces the listener to discover the relevance on their own.
Before and after
Before:
We moved this integration to an event-driven design with a queue between the services, and now retries are asynchronous instead of happening inside the request path.
After:
A temporary failure will no longer block the user request. The event is queued and retried separately, so the main trade-off is that some updates may arrive a little later. We need to decide whether that delay is acceptable for this process.
The technical mechanism is still there. It just appears after the consequence instead of before it.
Use three layers
- Consequence: what changes for the user, business process, risk or decision?
- Mechanism: what is the smallest technical explanation needed to understand why?
- Boundary: what trade-off, limitation or exception should not disappear?
If the audience asks for more depth, add another layer. Concision should make detail available on demand, not erase it.
Avoid the two common extremes
Do not dump implementation history just to prove expertise. Also do not flatten the explanation until it becomes false.
“It's faster now” may be too vague if the important fact is that processing became asynchronous. “It uses Kafka topics with consumer groups and retry queues” may be too detailed if the listener only needs to choose between immediate consistency and delayed processing.
Rehearse the explanation
Choose one technical change you know well.
Record a short version for a colleague outside your specialty. Listen once and answer:
- Did the consequence appear early?
- Did I explain the mechanism, or only name technologies?
- Did I preserve the important trade-off?
- Is it clear what the listener should decide, expect or do next?
Change one weak part and record again. Then explain the same mechanism using a different example or audience. If the explanation only works with one memorized analogy, it is not yet very portable.
Ptichi is being built to support this kind of spoken rehearsal and comparison without turning technical communication into a generic confidence score.
Reviewed: