Communication#

The single highest-leverage skill for any engineer. Clear communication reduces bugs, prevents rework, accelerates decisions, and builds trust. Poor communication does the opposite — at scale.

Written Communication#

Most engineering communication is written: Slack messages, emails, pull request descriptions, design documents, tickets, and documentation. Written words persist, get forwarded, and are read without your tone of voice for context.

The Pyramid Principle#

Lead with the conclusion, then provide supporting details. Busy readers need the answer first.

Pull Request Descriptions#

Your PR description is a communication tool, not a formality.

Email and Slack#

• Subject lines are headlines — make them scannable: “Decision needed: API versioning strategy by Friday”
• One message, one topic — don’t bury a question inside a status update
• Use threads — keep conversations findable
• Respect async — don’t expect instant replies. Provide full context so the reader can respond without follow-up questions

Technical Documentation#

Good docs answer: What is this? Why does it exist? How do I use it? What are the gotchas?

flowchart LR
    A[Reader arrives] --> B{What do they need?}
    B -->|Quick answer| C[README / Quick Start]
    B -->|Deep understanding| D[Architecture Doc]
    B -->|How to do X| E[How-To Guide]
    B -->|Something broke| F[Troubleshooting]

Verbal Communication#

Meetings and Presentations#

• State your point first, then elaborate — same pyramid principle as writing
• Use silence — pause after making a point. Let it land.
• Check understanding — “Does that make sense?” is weak. Try “What questions do you have?” or “Can you summarise what we agreed?”
• Adapt your depth — a 30-second answer is often better than a 5-minute one

Explaining Technical Concepts#

The Curse of Knowledge#

Once you understand something deeply, it becomes hard to remember what it was like not to know it. Fight this by:

• Defining acronyms on first use
• Using concrete examples before abstract principles
• Asking “what level of detail is helpful here?” before diving in
• Watching for glazed eyes or polite nodding

Active Listening#

Listening is not waiting for your turn to talk.

Practical Techniques#

• Paraphrase — “So what you’re saying is…” (confirms understanding, shows respect)
• Ask before solving — “Do you want me to help fix this, or do you just need to vent?”
• Silence after questions — count to 5 before filling the gap. Let them think.
• Take notes — it forces attention and signals respect

Audience Awareness#

Every communication has an audience. The same information needs different framing depending on who’s receiving it.

flowchart TD
    A[Information to communicate] --> B{Who is the audience?}
    B -->|Technical peer| C[Precise, detailed, assumes context]
    B -->|Cross-functional partner| D[Focus on interfaces and impact]
    B -->|Manager/Lead| E[Status, risks, decisions needed]
    B -->|Executive| F[Business outcome, one-liner]

Matching Communication to Context#

Technical vs Non-Technical Communication#

The ability to translate between technical and business language is a career accelerator.

The pattern: translate implementation details into impact on users, revenue, or speed.

Key Takeaways#

• Lead with the conclusion — readers and listeners are busy
• Match depth and vocabulary to your audience
• Written communication is permanent — invest in clarity
• Listening is an active skill that builds trust and surfaces better information
• The ability to translate between technical and business language makes you invaluable
• Every PR, email, and message is practice — treat them as communication reps