Presenting to Engineers
Mechanism, alternatives rejected, and what you are unsure about.
4 to work through
-
intermediate
A platform team's documentation is comprehensive and its users still ask questions it answers. What is wrong with the writing?
2 min answer -
intermediate
An architect's design is technically sound and the engineering team resists implementing it. What is usually the communication failure?
2 min answer -
intermediate
Six weeks after a design was agreed, three of its four key decisions are implemented differently and nobody raised it. The document has 18 comments with 16 of them from two people, 11 of 14 engineers opened it once, and the decision record was merged with two approvals in under four minutes. What do you conclude, which signal is misleading, and what would have caught this in week one?
3 min answer -
advanced
How do you get a team to adopt an approach they initially disagree with?
2 min answer
3 terms in this topic
Communicating with Engineers
Earning technical credibility and giving guidance that engineers act on — which depends more on how the reasoning is shared than on whether it is correct.
practiceDecision Restatement
Requiring the people who will implement a decision to write back what they will build and why, so that agreement is demonstrated by the receiver rath…
practiceTechnical Depth Calibration
Matching the level of detail and the mode of engagement to an engineering audience, which needs reasoning and the opportunity to disagree.
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.
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.