Soft Skills & Ecosystem Deep Dive · 1 of 12

Communication — The Multiplier

Senior engineers don't out-code juniors by 10× — they out-explain them. A clear PR description saves three reviewers an hour each. A clean design doc kills bad ideas before sprint-three. An honest incident update buys trust no dashboard can. Writing is the highest-leverage skill in this profession; speaking is a close second.

PR descriptionsDesign docsBLUFAsync-firstStakeholder framing
← Back to Soft Skills & Ecosystem
The Patterns

Formats Worth Mastering

FormatPurposeWhat good looks like
PR descriptionTell the reviewer why this change existsOne paragraph: what, why, how to test. Link the issue.
Design docAlign before code; capture the whyContext → goals → non-goals → options → decision → risks.
ADR (Architecture Decision Record)Pin a decision to a moment in timeStatus, context, decision, consequences. One page max.
Incident updateTell stakeholders what's known & what's nextImpact, what we know, what we're doing, next update time. Repeat at the cadence you promised.
Status updateAsync progress without a meetingWhat shipped, what's blocked, what I need. Headlines only.
Slack messageGet a fast answerLead with the question, not the prelude. Add context below.
Principles

How to Write So People Read

  • BLUF — Bottom Line Up Front. The most important sentence is the first one. Don't bury the headline.
  • One idea per paragraph. If a paragraph won't summarize in a sentence, split it.
  • Concrete > abstract. "p99 spiked to 4.2s" beats "performance degraded."
  • Show, don't tell. Numbers, screenshots, code samples. Then explain.
  • Pre-empt the questions. Read your draft as the busiest skeptic on the team.
  • Cut every word you can. If it doesn't change the meaning, delete it.
  • Match the audience. CFOs don't want pod restart counts; SREs don't want revenue narrative.
  • Permanence beats velocity. A doc you write once is read 50 times. Spend the time.
Speaking

Meetings, Demos, Pushback

  • Steel-man before you push back. Show you understood the other position before you disagree.
  • Disagree privately, support publicly. Once a decision is made, the team needs alignment, not litigation.
  • Demo, don't recite. A 90-second working flow beats 10 slides about it.
  • "I don't know — I'll find out by EOD." Better than guessing.
  • End every meeting with owners and dates. If nobody owns it by Friday, it didn't happen.
Tradeoffs

Pitfalls

  • Wall-of-text PRs. If the description is longer than the diff, split the PR.
  • Status theater. Updates with no decisions, blockers, or asks waste reader time.
  • Hedging. "I think maybe we could possibly..." → say it or don't.
  • Acronym soup. Spell things out the first time; remember new joiners.
  • "I'll just hop on a call." Two paragraphs of writing often beats a 30-min meeting and is searchable forever.
Continue

Other Soft Skills

Collaboration → Problem Decomposition → Documentation → Learning to Learn → ↑ Back to Soft Skills & Ecosystem