Scrolls
7 min read
On this page

Audience Awareness

Every piece of writing has a reader. If you do not know who that reader is, you are guessing — and guessing produces documents that serve no one well. Audience awareness is not a preliminary step you do before writing. It is the lens through which every sentence gets written, revised, and evaluated.

The same technical decision requires fundamentally different documents depending on who needs to understand it. An engineer needs implementation details. A manager needs timeline and risk. An executive needs business impact. An end user needs instructions. Writing one document for all four audiences produces something that frustrates everyone.

Identifying Your Reader

Before you write a single word, answer three questions:

1. Who will read this?
2. What do they already know?
3. What do they need from this document?

The answers determine everything: vocabulary, depth, structure, length, and tone. Get them wrong, and no amount of polished prose will save the document.

Most writing failures trace back to a mismatch between what the writer assumed about the reader and what the reader actually needed. You wrote a deep technical analysis. Your reader wanted a yes-or-no recommendation. You wrote a high-level summary. Your reader needed the SQL query.

Be specific about your audience. "Engineers" is too broad. A frontend engineer, a database administrator, and a machine learning researcher are all engineers with radically different contexts. "The three backend engineers on the payments team who will implement this" is a useful audience definition. "Engineers" is not.

Writing for Engineers

Engineers want to understand how things work. They read technical documents to make decisions, implement systems, debug problems, and evaluate trade-offs. They are comfortable with technical depth and expect it.

When writing for engineers:

  • Lead with the technical substance. Do not bury the architecture under three paragraphs of business context.
  • Use precise technical terms. If you mean "eventual consistency," say "eventual consistency." Do not say "the data takes a while to update everywhere."
  • Include concrete details: data formats, protocols, error codes, configuration parameters.
  • Show your reasoning. Engineers want to know why you chose this approach, not just what the approach is.
  • Reference specific systems, libraries, and tools by name.
For engineers:
"The service exposes a gRPC endpoint that accepts batched write
requests up to 1MB. Writes are buffered in memory using a ring
buffer (capacity: 10,000 entries) and flushed to PostgreSQL every
500ms or when the buffer reaches 80% capacity, whichever comes
first. We chose gRPC over REST for the 40% reduction in payload
size given our protobuf-heavy data model."

Engineers notice and respect precision. They lose trust when you hand-wave over details that matter.

Writing for Engineering Managers

Engineering managers care about execution. They need to understand enough of the technical picture to make resourcing decisions, assess risk, and communicate upward. They do not need to know the buffer flush interval.

When writing for engineering managers:

  • Lead with impact and timeline. What is changing, when, and what does the team need to do?
  • Translate technical risk into project risk. "The migration requires a schema change on a 2TB table" becomes "The migration includes a database change that will take 4-6 hours of downtime. We can schedule it for the maintenance window on Saturday."
  • Quantify where possible. Not "this will be faster" but "this reduces p99 latency from 800ms to 200ms."
  • Flag dependencies and blockers explicitly. Managers need to know what could delay the project.
  • Keep technical depth to the level needed for informed decision-making, not implementation.
For an engineering manager:
"We're proposing to migrate the payments service from REST to gRPC.
This will reduce API latency by ~40% and cut our monthly bandwidth
costs by approximately $3,200. The migration requires 2 engineers
for 3 sprints. Main risk: the mobile team needs to update their
client library, which depends on their Q3 roadmap. I've talked to
their lead and they can prioritize it if we commit by end of month."

Managers read for decisions. Give them what they need to say yes, no, or "tell me more about the risk."

Writing for Executives

Executives operate at the level of business outcomes, strategy, and resource allocation. They read dozens of documents per week. They will give yours two minutes, maybe five. If the first paragraph does not convey the essential message, they will not reach the third.

When writing for executives:

  • Lead with the business impact. Not the technology, not the architecture — the outcome.
  • Use plain language. If you must use a technical term, define it in the same sentence.
  • Keep it short. One page is ideal. Two pages is the maximum. If you need more, put details in an appendix.
  • Frame everything in terms of revenue, cost, risk, or customer experience.
  • Provide a clear recommendation or ask. Executives want to know what you need from them.
For an executive:
"Recommendation: Approve the payments infrastructure upgrade.

This upgrade will reduce payment processing failures by 60%,
recovering approximately $180K in lost monthly revenue. It
requires a $45K investment in engineering time (2 engineers,
6 weeks) and one scheduled maintenance window.

Risk: If we delay past Q3, we lose compatibility with our
payment provider's new API, which would require a more costly
migration ($120K+) in Q1 next year."

Notice what is absent: no mention of gRPC, protobuf, ring buffers, or flush intervals. The executive does not need those details to make the decision. Including them wastes their time and buries the point.

Writing for End Users

End users want to accomplish a task. They do not care about your architecture. They do not care about your technology choices. They care about what they can do and how to do it.

When writing for end users:

  • Use task-oriented headings. Not "Authentication Module" but "How to Log In."
  • Write step-by-step instructions with numbered lists.
  • Avoid internal terminology. Your database table names, service names, and internal acronyms mean nothing to users.
  • Anticipate errors and explain how to recover from them.
  • Test your instructions by having someone unfamiliar with the system follow them literally.
For end users:
"To export your data:

1. Click your profile icon in the top-right corner.
2. Select 'Settings' from the dropdown menu.
3. Scroll to 'Data Management' and click 'Export.'
4. Choose the date range you want to export.
5. Click 'Download.' Your file will be ready in about 2 minutes.

If you see 'Export failed,' your date range may be too large.
Try selecting a range of 6 months or less."

The test for good user documentation is simple: can a new user follow it without asking for help? If not, revise it.

The Same Information, Four Documents

Here is a concrete example. Your monitoring system detected that the application's error rate spiked to 15% during peak hours last Tuesday, caused by a database connection pool exhaustion.

To engineers:
"Connection pool exhaustion on prod-db-primary caused a 15% error
rate spike from 14:00-14:47 UTC on Tuesday. The pool (max_size=50)
was saturated by long-running queries from the new reporting
feature (avg query time: 12s vs normal 200ms). These queries held
connections while waiting on a table scan across the 800M-row
events table. Fix: added a read replica for reporting queries and
set a 5s statement_timeout on the primary pool."

To the engineering manager:
"Tuesday's outage lasted 47 minutes and impacted 15% of requests.
Root cause: the new reporting feature ran expensive database queries
that starved other features of database connections. We've deployed
a fix that isolates reporting queries to a separate database. No
recurrence expected. We're adding monitoring to alert before pool
saturation reaches critical levels."

To the executive:
"On Tuesday, 15% of customer requests failed for 47 minutes during
peak hours. Estimated impact: ~2,100 affected customer sessions.
Root cause identified and fixed within 2 hours. We've added
safeguards to prevent this class of issue from recurring. No
customer data was lost or compromised."

To end users (status page):
"Some users experienced errors between 2:00 PM and 2:47 PM UTC
on April 15. The issue has been resolved. If you encountered an
error during this time, please try your action again. We apologize
for the inconvenience."

Same event. Four different documents. Each one gives its audience exactly what they need.

Adjusting Depth, Jargon & Framing

Three dials control how you adapt writing to different audiences:

Depth determines how far into the details you go. Engineers need implementation-level depth. Managers need system-level depth. Executives need outcome-level depth. The mistake is not going too deep — it is going deep in the wrong places. An executive summary that includes a code snippet is a depth mismatch. An engineering spec that omits the wire protocol format is also a depth mismatch, just in the opposite direction.

Jargon is any term your specific reader does not understand. "Kubernetes pod" is not jargon when writing for your platform team. It is jargon when writing for the VP of Sales. The word itself is not the problem — the mismatch between the word and the reader's vocabulary is the problem. When in doubt, use the simpler term or define the technical one inline.

Framing is about what you emphasize. The same fact — "this migration will take 6 weeks" — can be framed as a cost ("this delays the product launch by 6 weeks"), a risk reduction ("investing 6 weeks now prevents a 6-month emergency rewrite later"), or a strategic move ("this positions us to handle 10x traffic growth next year"). Choose the frame that matters to your reader.

Common Pitfalls

Writing for yourself. You are not your audience. What you find interesting, clear, and well-structured may be irrelevant, confusing, and badly organized for your reader. Check your assumptions.

Mixing audiences in one document. A design doc that starts with an executive summary, then drops into implementation details, then resurfaces to discuss business impact is serving no one. Either write separate documents or use clear section boundaries with explicit labels ("For technical reviewers: ...").

Assuming your reader will ask if they are confused. They will not. They will skim past the confusing part, draw their own conclusion, and act on it. Or they will stop reading entirely. Confusion is silent.

Using jargon as a shortcut. Jargon feels efficient because it lets you say complex things in few words. But that efficiency only works when the reader shares your vocabulary. When they do not, jargon is not a shortcut — it is a wall.

Forgetting that audience awareness applies to informal writing too. Slack messages, code review comments, ticket descriptions — all of these have readers. A code review comment written for the author of the code is different from one written for future readers of the git log. Both are valid audiences, but they need different things.

Key Takeaways

  • Identify your specific reader before you write. "Engineers" is too vague. Name the team, the role, the context.
  • Answer three questions: Who will read this? What do they already know? What do they need from this document?
  • The same information requires fundamentally different documents for different audiences. Do not try to serve everyone with one document.
  • Adjust three dials for each audience: depth (how detailed), jargon (which terms need defining), and framing (what angle matters to this reader).
  • Engineers want precision and reasoning. Managers want impact and risk. Executives want business outcomes and recommendations. Users want step-by-step instructions.
  • When in doubt, write simpler. A reader who finds something too simple will skim faster. A reader who finds something too complex will stop reading.