Skip to main content

Audience-Aware Explanation: Exec, Peer, Junior, Customer

What This Concept Is​

The same technical content produces four different explanations depending on audience. The four audiences Staff+ engineers address most often:

  • Executive. Wants: outcome, cost, risk, what they should approve. Budget: 3 minutes or 3 sentences. Language: business, tradeoffs, dates.
  • Peer (senior engineer). Wants: model, alternatives, why this over that. Budget: 10-30 minutes. Language: precise technical, assumes shared context.
  • Junior engineer. Wants: concept, mental model, how to apply it. Budget: open-ended (onboarding doc, 1:1). Language: explicit assumptions, named patterns, "why" more than "what."
  • Customer / non-engineering stakeholder. Wants: what changes for them, when, and how to prepare. Budget: 1 page or 5 minutes. Language: business impact, zero jargon, no internals.

Each explanation is a different artifact, not the same doc with the jargon removed. Audience-aware explanation is the skill of producing the right artifact on purpose.

Why It Matters Here​

Senior engineers frequently produce one-size-fits-all explanations and wonder why no one responds to them:

  • exec bounces on a 10-page design doc because it never reached the decision
  • peer bounces on a 3-sentence summary because it has no model
  • junior bounces because it assumes context they have not built yet
  • customer bounces because it uses words they cannot act on

The cost of writing four artifacts is less than the cost of one misfire. A misfired exec summary delays a decision by a week. A misfired customer note triggers a support storm.

Concrete Example​

Same underlying change: migrating Orders service from Postgres to a new database.

Exec version (3 sentences).

We are migrating the Orders service from Postgres to DB-X. This is a one-quarter project costing ~$40k in cloud spend and ~8 engineer-weeks; it reduces weekly Orders latency incidents from ~3 to 0. Decision requested: approval to start in Q2.

Peer version (technical, 10 minutes). Context: Postgres is fine for our current load but breaks at our 18-month projection because of [specific write pattern]. Alternatives considered: sharding (rejected - operational cost); caching (rejected - cache-invalidation correctness); DB-X (selected because of [named property]). Tradeoffs: DB-X costs more at low load and less at high load. Migration path: dual-write for 6 weeks, shadow-read for 2 weeks, cutover. Risks: data-model impedance for the order_events table, mitigated by [plan].

Junior version (onboarding doc). This page explains why Orders uses DB-X and Postgres together for the next six months. First, a mental model: Orders service writes every order to both Postgres (authoritative) and DB-X (shadow) during the migration window. If you are writing code that reads orders, use [this client library] - it handles the dual-read logic for you. The reason for the migration is [short version]. The reason we do not just cutover is [correctness guarantee]. If you see a dual-write-mismatch alert, here is what to do.

Customer version (1 page for downstream service owners). Between Apr 15 and May 30, the Orders service will undergo a database migration. The Orders API contract does not change. Expected impact: ~200 ms latency increase during the 6-week dual-write window. During the final cutover window (May 28, 00:00-02:00 UTC), Orders writes will be briefly rejected; downstream services should retry. Contact: orders-oncall@.

Four artifacts. Same underlying engineering. Different outputs.

The Four-Audience Translation Test​

When an artifact is reused across audiences, a quick test catches most misfires. For each audience, ask:

  • Exec: If the VP reads only sentence one, do they know what to approve?
  • Peer: If a senior engineer on another team reads only the first page, can they argue with the choice?
  • Junior: If a six-month hire reads this page, can they apply the idea to their next PR or design?
  • Customer: If a non-engineering stakeholder reads the whole doc, do they know what they have to do and when?

A single document cannot pass all four tests. Authors who try to write one-doc-for-all produce a document that passes none of them. The fix is not to write four times more - it is to start from four different first sentences and let each artifact evolve from there.

A variant test: hand the artifact to someone in each audience and ask what their next action is. Silence, or "I'll follow up with questions," means the artifact failed for that audience. Adjust the artifact, not the reader.

Common Confusion / Misconception​

"The exec version is the peer version with the technical bits removed." No. The exec version is re-drafted from scratch, led by the decision request. Removing jargon from a 10-page doc produces a 10-page doc, not an exec summary.

"The junior version is the peer version with more explanation." Partly, but juniors need different structure, not just more words. They need named mental models and explicit decision points, not a longer expert monologue.

"Customers only need to know what breaks." They need to know: what changes, when, how to prepare, and where to get help. All four, or your inbox fills with the ones you skipped.

"If I write it clearly enough, any audience can read it." This is the core delusion. A document that serves all four audiences serves none of them well. Pick the audience before writing, not after.

"More audiences = more work = always worth it." Diminishing returns. Every audience you add is another artifact to keep in sync when the underlying decision changes. Produce variants where the audience has decision authority or operational impact; skip the variant for audiences who will not read or act on it.

"Translating into non-jargon is dumbing down." The opposite. Writing clearly for a non-expert audience is harder than writing for peers because you cannot lean on shared context. Teams that treat the customer variant as a less-important chore produce customer variants that cause outages and incidents.

Reading the Audience in Real Time​

Written audience adaptation is planned; live audience adaptation is harder. Three signals that tell you the audience in a room has shifted and your current explanation is wrong:

  • The exec's eyes go to their laptop. You are using peer-altitude language with an exec in the room. Stop, deliver a one-sentence decision recap, and offer to go deeper on request.
  • A junior goes quiet and stops asking questions. Your explanation has stepped past their mental model without noticing. Back up, name the concept, and re-anchor.
  • A peer starts rephrasing your sentence for the rest of the room. They are doing the audience-aware translation you should have done. Take over: ask them what they rephrased and use that wording going forward.

Noticing these signals is an advanced skill. Most engineers miss them for the first two years of senior-IC work and produce technically-correct explanations that do not land. The fix is to slow down by 20% and watch faces, not slides.

How To Use It​

Before writing, name the audience:

  1. Who is this for? One audience per artifact. If you need more, write more artifacts.
  2. What decision or action are they taking after reading? If none, consider whether the artifact should exist.
  3. What is their budget? 3 sentences, 1 page, 10 minutes, open-ended.
  4. What language do they use? Read their Slack or their docs. Match it.
  5. What question are they asking? Lead with the answer. Do not bury the action in the context.

Check Yourself​

  1. Name the four audiences in this module and what each is optimizing for.
  2. Why is the exec version not the peer version with jargon removed?
  3. What question should you ask yourself before writing any technical artifact?

Mini Drill or Application​

Take one recent technical decision you were part of. Produce four artifacts for it:

  • Exec version: 3 sentences ending in a decision request
  • Peer version: 1 page with model, alternatives, tradeoffs
  • Junior version: half-page onboarding note with a mental model
  • Customer version: half-page impact summary with dates and what to do

Then ask one person from each audience to read the matching version. Ask what they are missing. The answers are your feedback loop.

Transfer / Where This Shows Up Later​

Audience-aware explanation is the mechanism by which every prior concept reaches its actual readers:

  • Strategy and roadmaps (Concepts 4-6). A strategy doc has at least three audience variants: the body text (peer), the exec summary (exec), and the team-facing brief (junior/execution). A roadmap has an external-stakeholder version that hides capacity math.
  • Written-first (Concept 7). Each written artifact is already audience-tagged - an RFC's audience is engineering peers; an exec memo's audience is the VP. Confusion about audience is the most common reason a doc "doesn't land."
  • Stakeholder mapping (Concept 8). The stakeholder map tells you exactly which audience variants you need. Accountable -> exec version; Consulted -> peer; Informed -> customer or internal-broadcast.
  • Exec summary (Concept 11). The BLUF exec summary is the dominant exec-audience artifact. It is a special case of audience-aware explanation.
  • Architectural storytelling (Concept 12). The storytelling arc flexes per audience: execs get the choice and consequence; peers get the alternatives; juniors get the constraint; customers get the impact.
  • Feedback (Concept 14). SBI is itself an audience-aware move: the receiver is the audience, and the feedback's effectiveness depends on matching their context.
  • Semester 8 and beyond. M1 (interview communication), M2-M4 (cross-team explanations of service/data/reliability choices) all require audience variants. Semester 10 M5 on staff+ career notes the ability to "translate across altitudes and audiences" as a signature senior-IC skill.

Read This Only If Stuck​