Architecture Communication
General material on communicating architecture.
4 to work through
-
beginner
You have designed a system. Explain the same architecture to a CEO, an engineering manager and an engineer. What changes?
2 min answer -
intermediate
An architect presents the same architecture deck to executives, engineers and a security review board, and each audience is dissatisfied. What is wrong with the approach?
2 min answer -
intermediate
In a design review, a respected senior engineer proposes an approach you believe is wrong. The room defers to them. How do you handle it?
2 min answer -
advanced
An interviewer asks how you decide how much to say publicly, and how often, during an incident in which you have lost customer data. GitLab live-streamed its January 2017 database recovery and kept a publicly visible running document. Argue both sides of that level of disclosure, and say what you would commit to.
3 min answer
7 terms in this topic
Architecture Decision Log
The ordered, immutable collection of a system's decision records, read as a history rather than as a specification.
practiceC4 Model
A set of four nested diagram levels — context, container, component, code — that keeps each diagram at one consistent level of abstraction.
practiceData-Flow Diagram
A diagram of how data moves between processes, stores and external entities, with trust boundaries drawn on it.
practicePresenting to Engineers
Presenting a design at the level of mechanism, including the alternatives rejected and the parts you are still unsure about.
practicePresenting to Executives
Leading with the decision and the business consequence, at a level of abstraction where technology names do not appear.
practiceSequence Diagram
A diagram showing the ordered exchange of messages between participants over time, used to make an interaction's control flow and failure points explicit.
practiceTechnical Proposal
A written argument for a course of action, circulated for review before the work starts, structured so that disagreement surfaces early and cheaply.
Neighbouring topics
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.
Written Communication
Writing that survives being read without you in the room.
Facilitation
Running a design session that reaches a decision.