Communication & Writing

Clear writing is clear thinking. If you cannot explain a technical decision in writing, you probably do not fully understand it yet. At the senior level, communication stops being a soft skill & becomes one of the primary ways you create impact. Your code affects one system. Your writing affects every engineer who reads it, every manager who plans around it, & every executive who funds it.

Most engineers underinvest in communication because it does not feel like "real work." This is a mistake. A brilliant technical solution that nobody understands, nobody adopts, & nobody can maintain is not brilliant — it is a liability. The senior engineers who shape their organizations are the ones who can articulate what they are doing, why it matters, & what others need to know.

Writing as a Senior Skill

At mid-level, your communication radius is small: your team, your standup, your pull request descriptions. At senior, that radius expands to include other teams, product managers, engineering leadership, & sometimes customers. The quality bar rises with the audience.

Why Writing Matters More Than Speaking

Writing scales in ways that speaking does not. A conversation in a meeting reaches the people in the room. A well-written design document reaches everyone who needs the information, now & in the future. When a new engineer joins the team six months from now & asks "why did we choose Kafka over RabbitMQ?", the answer should be in a document — not in someone's memory.

Communication that scales:
- Design documents persist after the author leaves the team
- RFCs collect feedback asynchronously across time zones
- Post-mortems prevent the same incident from recurring
- Status updates keep stakeholders informed without meetings
- Architecture decision records preserve context for future teams

Writing also forces rigor. It is easy to wave your hands in a meeting & say "we should probably add a caching layer." It is much harder to write down exactly what you would cache, what invalidation strategy you would use, what the consistency trade-offs are, & what happens when the cache goes down. The act of writing exposes the gaps in your thinking before they become gaps in your system.

Writing Design Documents

Design documents are the primary artifact through which senior engineers influence technical direction. A good design doc does three things: it defines the problem precisely, it evaluates options honestly, & it recommends a path forward with enough detail that others can evaluate it.

Structure That Works

Design document template:
1. Problem statement (what is broken & why it matters now)
2. Background (what the reader needs to know to follow along)
3. Proposed solution (how it works, at the right level of detail)
4. Alternatives considered (at least two, with honest trade-offs)
5. Operational impact (monitoring, rollback, migration)
6. Open questions (what you are not sure about yet)

The most common failure in design documents is skipping the problem statement & jumping straight to the solution. If the reader does not understand why you are proposing a change, they cannot evaluate whether your solution is appropriate. A Senior engineer at a fintech company wrote a twelve-page design doc proposing a migration from REST to gRPC. The document was thorough — it covered performance benchmarks, schema evolution, & deployment strategy. But it never explained why the migration was needed. When the VP of Engineering asked "what problem does this solve for our customers?", the author could not answer concisely. The proposal was shelved. The technical work was strong. The communication failed.

Writing for Different Audiences

The same technical decision needs to be communicated differently depending on who is reading.

Audience          What they care about              Level of detail
────────────      ──────────────────────────────    ──────────────────────
Engineers         How it works, trade-offs, risks   High — show your reasoning
Eng managers      Timeline, staffing, dependencies  Medium — focus on execution
Product managers  User impact, delivery schedule    Low technical, high context
Executives        Business impact, cost, risk       Summary — one page or less

A real-world example: a senior engineer proposed replacing a legacy search service with Elasticsearch. For the engineering team, she wrote a detailed RFC covering indexing strategy, query performance benchmarks, & data migration. For her engineering manager, she wrote a one-page summary covering timeline (six weeks), staffing (two engineers full-time), & risk (fallback plan to keep the old service running). For the product lead, she wrote three sentences: the new search would support fuzzy matching & faceted filters, results would load 4x faster, & it would ship before the Q3 product launch.

Same decision. Three different documents. Each one gave the audience exactly what they needed to make their part of the decision.

Writing RFCs

RFCs (Requests for Comments) are a specific form of design document meant to gather feedback & build consensus on a proposal. They are how senior engineers drive decisions that affect multiple teams.

The key difference between a design doc & an RFC is the audience. A design doc might be read by your team. An RFC is read by anyone who has a stake in the outcome — which might be dozens of engineers across the organization.

RFC writing principles:
- State your recommendation up front — do not bury the conclusion
- Acknowledge trade-offs honestly — reviewers will find them anyway
- Include a "non-goals" section — what you are explicitly not solving
- Set a review deadline — open-ended RFCs collect dust
- Respond to every piece of feedback, even if only to say "acknowledged"

A common mistake is treating an RFC as a formality — writing the document after you have already decided & implemented the solution. This defeats the purpose. If reviewers sense that their feedback will not change anything, they stop engaging. An RFC that nobody comments on is not a sign of consensus. It is a sign that people have given up on the process.

Status Updates & Progress Communication

Senior engineers are expected to keep stakeholders informed without being asked. This means writing regular status updates that are concise, honest, & actionable.

The Weekly Update

A good weekly update answers three questions: what happened, what is coming next, & what is blocked. It takes ten minutes to write & saves hours of "can you give me an update?" meetings.

Weekly status update format:

Project: Payment Gateway Migration
Week of: March 23

Done:
- Completed API adapter for Stripe v3 (PR #2847)
- Load tested new endpoint — handles 2x current peak traffic
- Documented rollback procedure in runbook

Next:
- Begin shadow traffic routing (target: Wednesday)
- Write integration tests for edge cases (partial refunds, currency conversion)

Blocked:
- Waiting on Security team review of PCI scope change (requested March 18)
  Impact: cannot begin production rollout until approved

Notice what this update does not contain: jargon that only your team understands, vague statements like "making good progress," or a list of every commit you made. It gives the reader exactly enough context to know the state of the project & whether they need to do anything.

Post-Mortems

Post-mortems are the most important documents a senior engineer writes. They transform painful incidents into organizational learning. A good post-mortem is blameless, specific, & actionable.

Post-mortem structure:
1. Summary (what happened, in two sentences)
2. Impact (who was affected, for how long, severity)
3. Timeline (minute-by-minute during the incident)
4. Root cause (the actual underlying problem, not the trigger)
5. Contributing factors (what made the problem worse)
6. Action items (specific, assigned, with deadlines)
7. Lessons learned (what this incident taught us)

The root cause section is where most post-mortems fail. "The deploy had a bug" is not a root cause. "Our CI pipeline does not run integration tests against the production database schema, so the column rename was not caught before deploy" is a root cause — and it points directly to a fixable gap.

Async vs Sync Communication

Senior engineers need to know when to write & when to talk. The default should be async (written), with sync (meetings, calls) reserved for situations that genuinely require it.

Use async (writing) when:
- Sharing information that people need to reference later
- Gathering feedback from people in different time zones
- Documenting decisions so future team members have context
- The topic requires careful thought before responding

Use sync (meetings) when:
- There is active disagreement that written threads are not resolving
- The topic is emotionally sensitive (feedback, conflict, bad news)
- You need rapid back-and-forth to converge on a decision
- Building relationships with people you do not work with daily

A common anti-pattern is scheduling a meeting to share information that could have been an email. A worse anti-pattern is sending an email about a topic that requires a real conversation — like telling someone their project is being cancelled or delivering critical performance feedback.

The general rule: if you are transmitting information, write it down. If you are resolving disagreement or navigating emotion, have a conversation.

Presenting in Meetings

When you do need to present synchronously — in team meetings, architecture reviews, or leadership briefings — preparation matters more than charisma.

The Three-Point Rule

Every presentation should make no more than three points. If you are presenting a design proposal, your three points might be: the problem is costing us X, the proposed solution addresses it by doing Y, & the main risk is Z. If you are presenting a post-mortem, your three points might be: here is what happened, here is why, & here is what we are doing about it.

Presentation preparation checklist:
- What are my three points? (write them down)
- What is the one thing I need the audience to do or decide?
- What questions will they ask? (prepare answers for the top three)
- How long do I have? (plan to use 60% of it — leave room for discussion)

A Senior engineer at a healthcare company was asked to present a proposal to migrate from on-premise servers to cloud infrastructure. He prepared a forty-slide deck covering every technical detail. The VP of Engineering stopped him on slide six & asked: "What is this going to cost, & what do we get for it?" The rest of the slides were never shown. If he had led with the three-point summary — cost reduction of 30%, improved reliability from 99.5% to 99.95%, & migration timeline of four months — the conversation would have started in the right place.

Handling Questions

The best presenters are not the ones who never get challenged — they are the ones who handle challenges well. When someone asks a question you did not anticipate, it is fine to say "I do not have a good answer for that yet — let me follow up." This is infinitely better than making up an answer on the spot.

When you do follow up, do it in writing. Send the answer to the full audience, not just the person who asked. This turns a single question into shared knowledge & demonstrates that you take feedback seriously.

Handling tough questions in presentations:
- Pause before answering — silence is better than a rushed wrong answer
- Restate the question to confirm you understood it
- If you know the answer, be concise — do not over-explain
- If you do not know, say so & commit to a follow-up with a deadline
- If the question is out of scope, acknowledge it & offer to discuss offline
- Never get defensive — questions mean people are engaged

A senior engineer presenting an architecture proposal was challenged by a Staff engineer who pointed out a scalability concern. Instead of defending his design, he said: "That is a valid concern I had not fully worked through. Let me model the load at 10x current traffic & update the RFC by Friday." He sent the update on Thursday with a revised design that addressed the concern. The Staff engineer became one of his strongest supporters on the proposal.

Building a Writing Practice

Writing well is not a talent — it is a skill that improves with practice. The engineers who write the clearest design docs & the most useful post-mortems are not naturally gifted writers. They are engineers who write regularly & revise deliberately.

Start small. Write a brief summary after every meeting you attend — just for yourself. Describe what was decided, what is still open, & what you need to do next. This builds the habit of translating thoughts into words quickly. Over time, start sharing those summaries with your team. You will be surprised how much people appreciate it.

Read your writing out loud before sending it. Sentences that look fine on screen often sound awkward when spoken. If you stumble reading a sentence aloud, rewrite it. The goal is prose that flows naturally, not prose that demonstrates your vocabulary.

Ask someone you trust to review important documents before you send them widely. A second pair of eyes catches assumptions you did not realize you were making, jargon you did not realize you were using, & gaps you did not realize you were leaving.

Common Pitfalls

Writing for yourself instead of your audience. A design doc full of implementation details is useful for engineers but useless for the product manager who needs to understand the user impact. Always ask "who is reading this?" before you start writing.
Defaulting to meetings for everything. Meetings are expensive — they consume everyone's time simultaneously. Most information sharing & many decisions can happen asynchronously if you invest in clear writing.
Burying the conclusion. Engineers love to build up to a recommendation. Executives & busy stakeholders want the recommendation first, with supporting evidence available if they want to dig in. State your conclusion up front.
Treating post-mortems as blame exercises. The moment a post-mortem becomes about who made a mistake, people stop being honest. Blameless post-mortems focus on systems & processes, not individuals.
Writing too much. A ten-page design document for a two-day task wastes everyone's time. Match the weight of the document to the weight of the decision. A Slack message might be sufficient for a small change. An RFC is appropriate for a cross-team migration.
Never writing at all. Some senior engineers rely entirely on verbal communication. This means decisions live in memories, context is lost when people leave, & new team members have no way to ramp up. If it matters, write it down.
Skipping the "alternatives considered" section. Presenting only one option makes readers suspicious. Even if your recommendation is clearly the best choice, showing that you evaluated alternatives builds trust in your judgment.
Ignoring feedback on your writing. If multiple people misunderstand your document, the problem is your writing — not their reading comprehension. Treat confusion as a signal to revise.

Key Takeaways

Clear writing is clear thinking — if you cannot explain a decision in writing, you do not fully understand it yet.
Writing scales in ways that meetings do not. Documents persist, reach wider audiences, & preserve context for the future.
Design documents & RFCs are the primary tools through which senior engineers influence technical direction beyond their own team.
Always write for your audience: engineers need detail, managers need execution context, & executives need business impact summaries.
Default to async communication. Reserve sync (meetings) for active disagreement, emotional topics, & relationship building.
Status updates should answer three questions: what happened, what is next, & what is blocked. Keep them concise & honest.
Post-mortems are the most valuable documents you write — they transform incidents into organizational learning. Keep them blameless & focused on root causes.
When presenting, lead with your conclusion & limit yourself to three key points. Prepare for questions, & do not be afraid to say "I will follow up."
Match the weight of your communication to the weight of the decision. Not everything needs an RFC, but important decisions need to be written down.
Invest in your writing the way you invest in your code. Edit ruthlessly, seek feedback, & treat reader confusion as a bug in your communication.