Written Communication
Writing that survives being read without you in the room.
5 to work through
-
intermediate
A distributed engineering organisation makes architectural decisions in meetings and repeatedly relitigates them. What practice fixes this?
2 min answer -
intermediate
On 14 March 2023 Reddit was down for 314 minutes after an upgrade from Kubernetes 1.23 to 1.24 broke how Calico selected its route reflectors. Reddit published a detailed public write-up rather than a short root-cause statement. What did that choice buy them, and where would copying it be a mistake?
3 min answer -
intermediate
What makes a design document worth reviewing, and what makes reviewers ignore one?
2 min answer -
intermediate
Why does written architectural communication outperform meetings in a distributed engineering organisation, and what makes a document worth reading?
2 min answer -
advanced
In April 2022 an Atlassian maintenance script permanently deleted 883 sites belonging to 775 customers in 23 minutes, because a request passed between two teams did not say which identifiers or which deletion mode were meant. What does this say about written instructions as an engineering interface, and what would you change?
3 min answer
3 terms in this topic
Bottom Line Up Front
Placing the conclusion and the requested action in the first lines, on the assumption that most readers will not reach the end.
practicePublic Incident Narrative
An externally published account of an outage that transfers the diagnostic search rather than a conclusion - the timeline that was read, the hypothes…
practiceWritten Communication
Writing that reaches more people than any meeting, survives longer, and forces the thinking that verbal explanation lets you skip.
Neighbouring topics
Architecture Communication
General material on communicating architecture.
Architecture Diagrams
Choosing an audience and refusing to mix levels of abstraction.
C4 Model
Context, container, component and code as four separate diagrams.
Context Diagrams
The system as one box, with its users and external systems.
Sequence Diagrams
Ordered message exchange, and walking the failure of each arrow.
Data-Flow Diagrams
Following the data across trust boundaries rather than the calls.
Deployment Diagrams
What runs where, in which zone, behind which boundary.
Communicating Threat Models
Making risk legible to people who will fund or accept it.
Writing Decision Records
Context, alternatives and consequences, written once and never edited.
Technical Proposals
A written argument circulated before the decision feels made.
Architecture Reviews
Reviewing early enough to influence rather than to veto.
Presenting to Executives
Decision first, cost, risk, and what happens if we do nothing.
Presenting to Engineers
Mechanism, alternatives rejected, and what you are unsure about.
Explaining Trade-offs
Naming what was given up, and the condition that would change it.
Handling Disagreement
Arguing from consequences, and escalating in the room.
Negotiation
Trading on interests rather than positions, with priced options.
Documentation Practice
Keeping documents close to the code and honest about staleness.
Presentation Skills
Structure, pacing and the slide that carries the decision.
Facilitation
Running a design session that reaches a decision.