Chapter 23: Technical Communication
writing, documentation, design docs, RFCs, presentations, Minto pyramid, technical writing
Introduction
In 2018, a team at a major technology company spent six months building a sophisticated recommendation engine. The system was elegant: multi-armed bandits for exploration, collaborative filtering for personalization, real-time feature computation at scale. When they presented to leadership for production deployment approval, the meeting lasted twelve minutes. The executive sponsor asked three questions, received technically accurate but jargon-filled answers, and concluded that the team “didn’t seem to understand the business problem.” The project was shelved.
The same year, a competing team with a simpler approach—basic logistic regression with hand-crafted features—got full executive sponsorship within a week. Their technical lead had spent two hours crafting a three-slide deck that opened with customer impact metrics, showed the improvement trajectory over three phases, and closed with specific asks. The underlying system was less sophisticated, but the communication was superior.
Technical skill without communication skill limits your impact. You can design the most elegant system, but if you cannot explain it clearly, it will not get built. You can spot critical flaws in code review, but if you cannot articulate them constructively, your feedback will not land. You can have deep insights about technical direction, but if you cannot write a compelling RFC, your ideas will not influence decisions.
This pattern repeats across the industry. The engineers who shape technical direction are rarely the most technically brilliant—they are the ones who can translate complexity into clarity, who understand their audience deeply enough to meet them where they are, and who write documents that drive alignment rather than confusion.
The Core Insight: Communication as Leverage
Senior engineers are force multipliers. A junior engineer writes code. A senior engineer influences how an entire team writes code—through design documents that set patterns, code reviews that teach principles, and presentations that shift organizational understanding. All of this is communication.
The mathematics of leverage make this stark. Consider two senior engineers of equal technical ability:
- Engineer A spends 40 hours implementing a feature. Impact: one feature.
- Engineer B spends 30 hours implementing and 10 hours writing a design document that prevents three other teams from making the same architectural mistakes. Impact: the feature plus months of avoided rework across the organization.
The difference is communication. Engineer B understood that their insight had value beyond their immediate work and invested in transmitting it effectively.
This is why communication skills correlate strongly with career advancement in engineering. Not because organizations are wrong to value technical depth, but because communication is the mechanism through which technical depth creates organizational impact. A brilliant insight locked in one person’s head has no leverage. The same insight, clearly articulated in a widely-read document, shapes decisions for years.
Why This Matters for AI Engineers
AI engineering presents unique communication challenges. The field combines statistical concepts most stakeholders do not understand, system behaviors that are inherently probabilistic, and failure modes that defy simple explanation. When a recommendation system produces a surprising result, “the model learned a correlation between user behavior and this content type that we did not explicitly encode” is accurate but unsatisfying to most audiences.
AI engineers must bridge multiple worlds:
Technical to non-technical: Explaining model behavior to product managers, executives, and users requires translating probability distributions into decisions, uncertainty into risk, and training dynamics into intuitions.
Research to production: Academic AI communication optimizes for rigor and novelty. Production AI communication optimizes for actionability and risk management. The same model advancement requires different framing for each context.
Complexity to simplicity: AI systems are genuinely complex. Effective communication does not pretend otherwise—it finds the right level of abstraction for each audience and context.
Uncertainty to confidence: Leaders want clear recommendations. AI systems produce probabilistic outputs. Navigating this gap requires honest communication about confidence levels without paralysis or false precision.
A Mental Model for Technical Communication
Think of communication as signal transmission through a lossy channel. You have information in your head. The receiver needs a subset of that information to take appropriate action. Between you and them lies a channel—a document, a presentation, a conversation—that can only transmit so much.
Effective communication is not about transmitting everything you know. It is about:
Understanding what the receiver actually needs: What decision will they make? What action will they take? What must they understand to do so correctly?
Selecting the right information: Given their needs, what subset of your knowledge is essential? What is helpful context? What is noise?
Encoding for the channel: A document transmits differently than a presentation. A Slack message transmits differently than an email. Choose the right channel and encode appropriately.
Reducing noise: Every sentence that does not serve the receiver’s needs is noise that obscures signal. Edit ruthlessly.
Enabling verification: Good communication lets receivers check their understanding. Structure, examples, and explicit statements of intent all help.
This model explains why brilliant engineers sometimes communicate poorly. They optimize for completeness (transmitting everything) rather than relevance (transmitting what matters to this receiver). They forget that the channel is lossy and that the receiver’s processing capacity is limited.
What You Will Learn
- How communication theory applies to technical writing and speaking
- Frameworks for audience analysis and message adaptation
- The structure of effective design documents and RFCs
- Principles of constructive code review
- Visual communication for complex technical concepts
- How to drive decisions through clear argumentation
- Case studies of communication successes and failures
Prerequisites
- Experience working on technical teams
- Familiarity with design and code review processes
- Basic writing and presentation experience
- Reading: Chapter 7’s example of structured technical writing
The Theory of Technical Communication
Document Design Theory
Research in document design, pioneered by scholars like Karen Schriver and Janice Redish, reveals that readers do not process documents linearly. Eye-tracking studies show that readers scan documents in predictable patterns, focusing on headings, opening sentences, and visual elements before (if ever) reading body text.
This has profound implications for technical writing:
The F-pattern: Readers scan horizontally across the top, then move down and scan a shorter horizontal line, then scan vertically down the left side. Structure your documents so that critical information appears in these high-attention zones.
Front-loading: The first words of headings, paragraphs, and sentences receive disproportionate attention. Put the most important information first.
Chunking: Working memory holds approximately four chunks of information at a time. Break complex information into chunks, with clear boundaries between them.
Signal words: Words like “however,” “therefore,” and “importantly” signal document structure and guide reader attention. Use them deliberately.
Traditional document structure—introduction, body, conclusion—is exactly backward for busy professional readers. They need to know the conclusion first to decide whether to invest in understanding the reasoning.
The Minto Pyramid Principle, developed at McKinsey in the 1960s, formalized this insight: start with the answer, then provide supporting arguments, then provide supporting data. Every level answers the question “why?” or “how?” for the level above it.
For a design document, this structure translates to:
- Recommendation: “We should build X using approach Y”
- Supporting arguments: “Because it solves the core problem, integrates with existing systems, and is achievable in our timeline”
- Supporting data: Requirements analysis, architecture diagrams, risk assessment, alternatives comparison
Audience Analysis
Aristotle’s framework for persuasion—ethos, pathos, logos—remains relevant two millennia later. Technical communication requires all three:
Logos (logical appeal): The technical argument must be sound. Data must support conclusions. Alternatives must be fairly evaluated. This is where most engineers focus, and it is necessary but not sufficient.
Ethos (credibility): The audience must believe you are competent and trustworthy. This is established through demonstrated expertise, acknowledgment of uncertainty, fair treatment of alternatives, and a track record of sound judgment.
Pathos (emotional connection): The audience must care about the outcome. This is not about manipulation—it is about connecting your proposal to things the audience genuinely values. An engineer proposing a refactoring must connect it to outcomes leadership cares about: velocity, reliability, developer retention.
Modern audience analysis adds specificity. Before communicating, ask:
What do they already know? Assumptions about shared knowledge are a primary source of communication failure. Overestimate the context you need to provide.
What do they need to do? Communication succeeds when the receiver takes appropriate action. What action do you want, and what must they understand to take it?
What concerns might they have? Anticipating objections and addressing them proactively builds credibility. Ignoring obvious concerns undermines it.
How do they prefer to receive information? Some stakeholders want written documents before meetings. Others prefer verbal walkthroughs. Some want data-heavy slides. Others want narrative flow. Adapt to the receiver.
What is their current mental model? New information is understood in terms of existing frameworks. If your proposal contradicts their mental model, you must first update that model, or your proposal will be rejected or misunderstood.
The Curse of Knowledge
The curse of knowledge is a cognitive bias in which experts cannot remember what it was like not to know something. This makes expert communication systematically biased toward being too complex, too jargon-filled, and too context-light.
Research by Elizabeth Newton (1990, Stanford PhD dissertation) demonstrated this dramatically. Participants “tapped” well-known songs on a table while other participants tried to guess the songs. Tappers estimated that listeners would identify about 50% of songs. Actual identification: 2.5%. Tappers could not imagine not hearing the melody they knew. (This study was later popularized by Chip and Dan Heath in Made to Stick.)
Every technical document you write is a form of tapping. You hear the melody—the context, the constraints, the implications—but your reader does not. Defeating the curse of knowledge requires:
User testing: Have someone from your target audience read your document and explain it back to you. Where they stumble is where your curse of knowledge created confusion.
Explicit context: State things you think are obvious. They are not obvious to your reader. When in doubt, include more context.
Concrete examples: Abstract explanations engage the curse of knowledge. Concrete examples anchor understanding in shared reality.
Editing time: Distance from your writing helps you see it more objectively. Edit important documents after sleeping on them.
Visual Communication
Research consistently demonstrates that human visual processing is faster and more parallel than text processing. Edward Tufte’s work on visual display of quantitative information established principles that apply directly to technical communication:
Data-ink ratio: Maximize the proportion of ink devoted to data versus decoration. Every visual element should convey information.
Small multiples: Show variations through repeated similar graphics rather than trying to cram everything into one complex visualization.
Layering and separation: Use visual hierarchy to distinguish primary information from secondary context.
For technical communication specifically:
Architecture diagrams should show component relationships with consistent abstraction levels. Do not mix high-level service boxes with detailed class diagrams.
Sequence diagrams clarify temporal relationships that are confusing in prose. Any scenario involving multiple components interacting over time benefits from a sequence diagram.
Data flow diagrams show how information moves through a system. They are especially valuable for explaining ML pipelines where data transformations are the core logic.
Before/after comparisons make change proposals concrete. Show the current state and the proposed state side by side.
A well-designed diagram often communicates in seconds what paragraphs of text cannot communicate in minutes. The investment in diagramming pays off in reader comprehension.
Visualizing AI Results: Distributions, Not Points
Tufte’s principles take on a sharper edge in AI engineering because the single most common visualization mistake in our field is reporting a model’s quality as one number. “92% accuracy” is a point estimate that hides everything a reader needs to make a decision: how that number varies across the inputs that matter, how confident you are in it, and whether it is stable over time. Three patterns are worth internalizing.
Plot the distribution, not the mean. Eval scores are samples, not constants. A model that averages 0.82 on a faithfulness metric with most outputs clustered between 0.78 and 0.86 is a very different system from one that averages 0.82 by mixing many near-perfect outputs with a long tail of near-zero failures—yet both report the same number. Show the histogram or a box plot of the per-example scores. The shape of the tail is usually where the decision lives.
Break out per-segment quality. A single aggregate number is a weighted average across segments that may behave nothing alike. Use small multiples (Tufte’s term)—one consistent chart repeated per cohort—to show accuracy or quality side by side across the segments that matter: by language, by customer tier, by input length, by the high-stakes cohort you most need to get right. A model that is 90% accurate overall can be 95% on the easy majority and 60% on a critical minority; the aggregate actively hides the risk.
Track quality over time. Models that pass evaluation at launch degrade as input distributions drift. A run chart of your headline metric per release (or per day, scored against a fixed golden set) turns silent regression into a visible trend. Annotate it with deploys and known data-distribution changes so the reader can connect cause to effect.
The reason a single accuracy number misleads is structural, not cosmetic: aggregation discards exactly the variance and segment structure that determine whether a system is safe to ship. A good AI results visualization restores that structure. When you find yourself about to put one bold percentage on a slide, ask what distribution, what segments, and what trend that number is flattening—and plot one of those instead.
Design Documents
Why Design Documents Matter
Design documents are the primary vehicle through which engineers influence technical direction at scale. A well-written design document:
Clarifies your thinking: Writing forces you to think through details you might otherwise skip. The discipline of explaining your approach to others reveals gaps in your own understanding.
Enables feedback before investment: It is much cheaper to discover flaws in a design document than in implemented code. Review while the cost of change is low.
Aligns stakeholders: Everyone who reads the document understands what will be built and why. This prevents the expensive misalignment that occurs when people have different mental models of the same project.
Creates institutional memory: Future engineers can understand why decisions were made. This is invaluable for maintenance, extension, and learning from history.
Scales your influence: A design document can be read by dozens of people. Your direct conversation can only reach a few. Documents scale your communication.
Case Study: The Stripe API Design Document
In Stripe’s early years, their API design documents became legendary in the developer tools community. Michelle Bu and other engineers created documents that were so clear about principles and tradeoffs that they influenced API design across the industry.
What made these documents exceptional:
Principles before features: The documents articulated design principles (consistency, predictability, error handling philosophy) before diving into specific endpoints. This allowed readers to understand the reasoning, not just memorize the decisions.
Real examples, not abstract specifications: Instead of describing “an endpoint to create resources,” they showed the actual request and response for creating a charge. Concrete beats abstract.
Explicit tradeoff discussions: When the design chose simplicity over flexibility (or vice versa), the document explained why. This built credibility and helped readers understand when to apply the same reasoning.
Living documents: The design documents were updated as understanding evolved. They included sections for decisions that were reconsidered and why.
This approach transformed design documents from bureaucratic artifacts into competitive advantages. Engineers wanted to work at Stripe partly because the design documents helped them learn faster.
Structure of an Effective Design Document
Writing for Multiple Audiences
A design document has multiple readers with different needs:
Engineers who will implement: They need precise technical specifications. API contracts, data models, error handling behavior, performance requirements. They will reference this document repeatedly during implementation.
Engineers who will review: They need enough context to evaluate the approach and enough detail to spot issues. They may not become experts in this system—they need to understand it well enough to give useful feedback.
Technical leads and architects: They need to assess architectural alignment. Does this approach fit with broader system design? Does it set appropriate precedents? Does it introduce unnecessary complexity?
Product managers: They need to understand scope, timeline, and tradeoffs. They care less about implementation details and more about what is being built, when it will be available, and what is being traded off.
Future maintainers: They need to understand why decisions were made. “We chose X” is less valuable than “We chose X because of constraints A and B; if those change, reconsider this decision.”
Write the main document for technical reviewers—enough detail to evaluate the approach, not so much that it is unreadable. Put implementation specifications in appendices. Put timeline and scope summaries in an executive summary at the top.
The Alternatives Section
The alternatives section is where many design documents fail. Weak patterns:
“No alternatives considered”: Signals that you have not explored the solution space. How do reviewers know this is a good approach if you have not compared it to others?
Straw-man alternatives: Presenting obviously bad alternatives to make your proposal look good. Reviewers recognize this tactic and lose trust.
Missing the obvious alternative: If there is a standard approach in your organization or industry and you are not using it, you must address why. Not mentioning it looks like ignorance.
Strong alternatives sections demonstrate that you have thought carefully about the solution space and chosen this approach for specific, articulable reasons:
Alternative A: Use existing service X
This would avoid building new infrastructure but does not meet our latency requirements. Service X has a p99 latency of 500ms; we need sub-100ms. Additionally, their API does not support the filtering we need without significant post-processing.
Alternative B: Build a custom solution from scratch
This would give us maximum flexibility but significantly increases scope. Our estimate is 6 months versus 2 months for the proposed approach. Given that we need this capability for the Q2 launch, the timeline does not work.
Alternative C: Use managed service Y from cloud provider
This was our initial preference. After evaluation, we found that their cold-start latency (2-3 seconds) makes it unsuitable for our interactive use case. We had extended discussions with their team about improvements, but they have no plans to address this in the next year.
Notice how each alternative receives genuine consideration, with specific reasons for rejection. This builds credibility and helps reviewers understand the constraints shaping the decision.
When to Write a Design Document
Not every change needs a design document. The investment must match the value:
Write a design document when:
- Work will take more than a week of effort
- The decision affects multiple components or teams
- The decision would be expensive to reverse after implementation
- The approach is not obvious—reasonable engineers might disagree
- Future engineers will need to understand the reasoning
- Failure would have significant consequences
Skip the design document when:
- The change is straightforward bug fix or small feature
- Well-established patterns clearly apply
- You are doing an experimental spike that may be discarded
- Building is faster than documenting (rare for any substantial work)
When in doubt, write a shorter document rather than no document. A one-page design document that captures the key decision and reasoning is far more valuable than either no document or a document so lengthy that no one reads it.
The Review Process
Design reviews are collaborative problem-solving, not adversarial examination. The goal is better designs, not winning arguments.
Before the review:
- Share the document with reviewers at least 24-48 hours before any meeting
- Identify specific areas where you want feedback: “I am uncertain about the caching strategy”
- Make the document easy to comment on (collaborative editing tools help)
During review:
- Listen more than you defend
- Ask clarifying questions: “Can you say more about the concern with X?”
- Distinguish blocking feedback from suggestions
- Take notes on feedback even if you disagree—you may see it differently later
After review:
- Address every piece of feedback explicitly
- Update the document to incorporate changes
- Document decisions made and their rationale
- If you disagree with feedback, explain why rather than ignoring it
Common Failures
The novel: Fifteen pages when three would suffice. Long documents signal either unclear thinking or lack of editing discipline. Either undermines credibility.
The implementation plan: Detailed code specifications without higher-level reasoning. Readers cannot evaluate whether the approach is good if they do not understand the problem it solves.
The sales pitch: Enthusiastic description of benefits without honest assessment of costs, risks, and tradeoffs. Readers lose trust when the document reads like advocacy rather than analysis.
The post-hoc rationalization: Documents written after implementation to satisfy process requirements. These miss the value of design documents—clarifying thinking and enabling feedback before investment.
The abandoned document: Documents that are never updated as understanding evolves. They become misleading artifacts. Either keep them current or mark them as historical.
RFCs and Technical Proposals
The Purpose of RFCs
Request for Comments documents, a tradition dating to the early internet (RFC 1 was published in 1969), formalize proposals that affect multiple teams or establish long-term precedents. They differ from design documents in scope and formality.
RFCs are appropriate when:
- The change affects multiple teams who must coordinate
- You are establishing a new standard or pattern
- You are deprecating existing systems that others depend on
- The decision has significant long-term implications
- Cross-functional alignment is required
The formality of RFCs serves a purpose: it ensures that significant decisions receive appropriate consideration from affected stakeholders and creates an auditable record of organizational decision-making.
Case Study: The Rust RFC Process
The Rust programming language’s RFC process is widely admired for balancing community input with decisive action. Key characteristics:
Public by default: RFCs are visible to the entire community, enabling broad feedback and transparency about how decisions are made.
Structured discussion period: Each RFC has a defined comment period. This prevents premature closure while avoiding indefinite bikeshedding.
Final comment period: Before acceptance, an RFC enters a final comment period with explicit disposition. Stakeholders have one last chance to raise concerns.
Champion model: Each RFC has a champion responsible for driving it through the process, incorporating feedback, and advocating for the proposal.
Clear acceptance criteria: RFCs are accepted when the relevant team reaches consensus that the benefits outweigh the costs. “Consensus” does not mean unanimity—it means that no one has unaddressed blocking concerns.
This process has enabled Rust to make significant language changes with broad community buy-in while maintaining momentum on development.
RFC Structure
# RFC: [Title]
## Summary
[One paragraph description of the proposal]
## Motivation
[Why are we doing this? What problem does it solve? What use cases does it support?]
## Detailed Design
[Technical specification of the proposal. This should be detailed enough that someone could implement it.]
## Drawbacks
[Why should we NOT do this? What are the costs and risks?]
## Alternatives
[What other designs were considered? Why was this design chosen?]
## Prior Art
[How have others solved similar problems? What can we learn from them?]
## Unresolved Questions
[What aspects of the design need further discussion or research?]
## Future Possibilities
[What future work might this enable? What is out of scope now but related?]The Drawbacks section is crucial. A proposal that claims to have no drawbacks is either not understood or not honestly assessed. Every significant decision involves tradeoffs. Acknowledging them builds credibility and helps readers make informed judgments.
Building Consensus
RFCs require building consensus across stakeholders who may have different priorities, perspectives, and information.
Socialize early: Before formal RFC submission, discuss your ideas with key stakeholders. Incorporate their feedback into your initial draft. This prevents surprises and builds allies.
Identify the right stakeholders: Who will be affected by this decision? Who has relevant expertise? Who has decision-making authority? Missing a key stakeholder early creates problems later.
Engage with concerns genuinely: When someone raises an objection, resist the urge to immediately defend your position. Understand their concern fully. Often, they see something you missed. Even when you disagree, demonstrating that you understand and have considered their concern builds trust.
Find common ground: Most disagreements are not about fundamental values but about predictions (what will happen if we do X) or priorities (which outcome matters more). Clarifying where you actually disagree often reveals paths to resolution.
Accept that consensus requires compromise: Your original proposal may not survive contact with stakeholders. Be willing to modify your approach when feedback is valid. Rigid insistence on your initial design signals that you value being right over finding the best solution.
Know when to escalate: If consensus cannot be reached, know when and how to escalate to decision-makers with broader authority. Escalation is not failure—it is appropriate when stakeholders have irreducible disagreements.
The RFC Lifecycle
Draft phase: Work with close collaborators to refine the idea. Fix obvious problems before broader exposure. This is not about hiding the proposal—it is about not wasting stakeholders’ time on versions with obvious gaps.
Proposal phase: Announce the RFC through appropriate channels. Set clear expectations about the review period and how to provide feedback.
Review phase: Actively engage with feedback. Update the RFC to address comments. Track which concerns have been resolved. When appropriate, summarize discussions in the document.
Decision phase: After adequate review, the RFC is accepted, rejected, or withdrawn. Document the rationale for the decision, including key arguments on all sides.
Implementation phase: Accepted RFCs guide work. Reference them in related pull requests and design documents. Update them if implementation reveals issues.
Common RFC Failures
Surprising stakeholders: If the RFC is the first time affected teams hear about a significant change, you have already failed. Early socialization is not optional.
Weak motivation: If you cannot clearly explain why this change matters, the RFC will struggle. Motivation should answer “why now?” and “why this approach?” not just “what?”
Defensive response to feedback: Treating objections as attacks rather than input destroys the collaborative process. Even when objections are wrong, they reveal that your communication was unclear.
Abandoning accepted RFCs: An accepted RFC creates expectations. If circumstances change and the RFC will not be implemented, formally supersede or withdraw it. Orphaned accepted RFCs create confusion.
Process as substitute for judgment: An RFC that follows all formal requirements but does not represent genuine engagement with stakeholders is worse than useless—it creates the illusion of alignment without the reality.
Code Review
Code Review as Communication
Code review is one of the most frequent forms of technical communication. Research by Bacchelli and Bird (2013) found that while engineers believe code review is primarily about finding defects, the actual primary benefits are knowledge transfer and code improvement suggestions. This reframes what effective code review looks like.
If code review were primarily about defect detection, optimal strategy would be detailed, skeptical examination of every line. But if it is primarily about knowledge transfer and improvement, optimal strategy emphasizes teaching, context sharing, and collaborative refinement.
This does not mean defects do not matter—they do. But reviews that focus exclusively on finding bugs while providing no context, no teaching, and no encouragement often fail to achieve their most valuable outcomes.
What to Review
Not all aspects of code are equally important. Prioritize accordingly:
Always review carefully:
- Correctness: Does the code do what it is intended to do? Are there edge cases that cause failures?
- Security: Are there vulnerabilities? Input validation issues? Authentication or authorization gaps?
- Design: Is the approach sound? Will this be maintainable? Does it fit with the surrounding system?
Review when relevant:
- Performance: Are there obvious inefficiencies that will matter at scale?
- Error handling: What happens when things go wrong? Are errors logged? Surfaced appropriately? Recoverable?
- Testing: Are tests adequate? Do they test behavior, not just implementation details?
Do not block on:
- Style: Formatting, naming conventions, and similar issues should be automated. If your linter does not catch it, it probably does not matter enough to block.
- Personal preferences: “I would have done it differently” is not a blocking concern unless “differently” is meaningfully better.
Writing Effective Review Comments
The tone and structure of review comments significantly affect whether they improve code or create conflict.
Ineffective comment: > This is wrong.
Effective comment: > [Concern] This will throw a NullPointerException if user is null, which can happen when the session expires. Consider adding a null check, or using Optional to make the potential absence explicit.
The effective comment:
- Labels the type (concern, question, suggestion, nit)
- Explains the issue specifically
- Explains why it matters (what goes wrong)
- Suggests a solution or path forward
Ineffective comment: > Why did you do it this way?
Effective comment: > [Question] I am curious about the choice to use a list here instead of a set. Was there a requirement to preserve insertion order, or would a set work? If order matters, maybe worth a comment explaining why.
The effective comment:
- Signals genuine curiosity rather than accusation
- Provides context for the question
- Suggests what would help (a clarifying comment)
Receiving Review Feedback
How you receive feedback affects your growth and your relationships with colleagues.
Assume good intent: Reviewers want to help. If a comment seems harsh, consider that text lacks tone. Assume the most charitable interpretation.
Ask clarifying questions: If feedback is unclear, ask for elaboration rather than guessing or ignoring.
Explain your reasoning: If you disagree, explain why. You may have context the reviewer lacks. But do so in a way that invites dialogue, not shuts it down.
Accept that you might be wrong: Your first instinct to defend your code is natural but often wrong. Consider the feedback genuinely before responding.
Thank reviewers: Especially for thorough reviews. Recognition encourages future effort and builds relationships.
Case Study: Google’s Code Review Practices
Google’s engineering culture treats code review as a core competency, not a bureaucratic hurdle. Research by Sadowski et al. (2018) documented their practices:
Readability certification: Engineers earn “readability” in each language through a rigorous review process. Only readability-certified engineers can approve code in that language. This ensures consistent quality standards.
Small CLs (changelists): Google’s tooling and culture encourage small, focused changes. Smaller reviews are faster, more thorough, and less contentious. Research shows review quality drops significantly beyond a few hundred lines.
Speed expectations: The median time for initial response to a code review is about one hour during business hours. Fast turnaround keeps the review process from becoming a bottleneck.
Comments as teaching: Senior engineers treat reviews as teaching opportunities. They explain not just what to change but why, often linking to style guides, documentation, or previous examples.
This approach transforms code review from a gatekeeping function into a continuous learning system. Junior engineers learn from every review, and the codebase maintains high quality through consistent standards.
Reviewing AI/ML Code
AI and ML code presents unique review challenges:
Data dependencies: ML code often depends on data characteristics that may not be obvious from the code itself. Ask about data assumptions and edge cases in the data distribution.
Stochastic behavior: ML systems behave probabilistically. Tests should account for variance. Review tests to ensure they are not just confirming one random outcome.
Training-serving skew: Feature computation must match between training and serving. Review carefully for any differences in data processing pipelines.
Metric validity: Are the metrics being computed actually measuring what matters? Review both the computation correctness and the metric choice.
Experiment integrity: For ML experiments, review the experimental design: baseline comparisons, statistical significance, and reproducibility.
These risks are easy to list and hard to catch, because the code usually looks fine. A useful review comment names the ML-specific failure mode explicitly and ties it to a concrete scenario, the same way the general examples above do. Consider a PR that adds a test for an LLM-powered summarization endpoint:
def test_summarize():
result = summarize(ARTICLE)
assert result == "The Fed raised rates by 0.25% to combat inflation."Ineffective comment: > [Nit] Maybe loosen this assertion a bit?
Effective comment: > [Concern, blocking] This asserts an exact string against an LLM output, which is non-deterministic even at temperature 0 (model updates, tokenizer changes, and provider-side rounding all shift wording). This test will pass today and flake or hard-fail on the next model version, training the team to ignore it. Suggest asserting on properties instead: that the summary is non-empty and under the length cap, mentions the key entities (“Fed”, “rates”), and—if we want quality coverage—scoring it with our LLM-as-judge harness against a threshold rather than an exact match. Happy to pair on the judge setup if useful.
The effective version names the specific risk (asserting exact output against a stochastic system), explains the concrete failure trajectory (passes now, breaks on the next model bump, erodes trust in the suite), and offers a property-based alternative the author can act on. The same pattern works for training-serving skew: rather than “double-check the features,” write “[Concern] this normalizes the amount feature using stats computed in this request handler, but training normalized against the offline dataset’s mean/std—if those differ, we get training-serving skew that silently degrades predictions. Can we load the same fitted scaler both places?”
Common Review Failures
Rubber stamping: Approving without reading because you trust the author or are too busy. This provides none of code review’s benefits and creates false confidence.
Blocking on preferences: Using blocking status for stylistic preferences. This signals that you value your preferences over the team’s productivity.
Delayed reviews: Letting reviews sit for days. Fast turnaround keeps teams productive. If you cannot review promptly, say so and suggest another reviewer.
Reviewing too much at once: Large reviews get superficial attention. Better to request the PR be split than to provide inadequate review of a large change.
Public criticism for private matters: Comments about someone’s patterns of behavior, competence, or effort belong in private conversation, not code review comments.
Technical Presentations
“We wanted to rebuild the recommendations stack and the VP killed it twice. Third time I rewrote the deck with one change: I moved the slide showing $4.2M/year in incident response costs from slide 14 to slide 2. Same data, same proposal, 12 minutes of meeting. Approved. Executives decide in the first 3 minutes—everything after that is them building justification for what they already concluded. Now I write every recommendation deck backwards: what’s the one number that, if they only saw that, would force a yes? That goes on slide 2. Slide 1 is just context for the number.”
— Director of ML Engineering at a media streaming company
Why Presentations Differ from Documents
Documents and presentations serve different purposes and require different approaches:
Documents allow non-linear consumption: Readers can skim, jump to sections, and read at their own pace. They can re-read confusing parts.
Presentations are linear and transient: Listeners hear each point once, in order, at the speaker’s pace. They cannot easily revisit earlier points.
Documents suit detail and reference: Technical specifications, API documentation, and design records belong in documents.
Presentations suit narrative and persuasion: Getting buy-in on a direction, explaining context, and building shared understanding work better in presentations.
This means you should not simply read your document aloud. A presentation requires restructuring content for linear consumption, reducing detail, and adding narrative arc.
Presentation Structure
Research on attention and memory suggests that listeners remember beginnings and endings better than middles (the primacy and recency effects). Structure accordingly:
Audience Adaptation
The same technical content requires different presentation for different audiences:
For engineers:
- Emphasize how it works: architecture, algorithms, implementation details
- Include code examples and diagrams
- Discuss technical tradeoffs
- Expect detailed questions about edge cases and performance
- Jargon is acceptable—they speak the same language
For leadership:
- Emphasize why it matters: business impact, risk reduction, strategic value
- Lead with outcomes and implications
- Quantify when possible: latency improvements, cost reductions, velocity gains
- Prepare for questions about timeline, resources, and risks
- Avoid jargon—translate to business concepts
For cross-functional partners:
- Emphasize what it enables: new capabilities, constraints removed, dependencies
- Focus on the interface, not the implementation
- Discuss timeline and dependencies
- Prepare for questions about user impact and integration
- Use just enough technical detail to build credibility
Case Study: The Steve Jobs Keynote
Steve Jobs was legendary for presentations that made complex technology feel simple and desirable. Analysis of his techniques reveals transferable principles:
One theme: Each presentation had a single, memorable theme. The iPhone launch was “Apple reinvents the phone.” Everything supported that theme.
Dramatic structure: Presentations had setup, conflict, and resolution. Problems were stated before solutions were revealed. This created narrative tension.
Demos over slides: Whenever possible, Jobs showed rather than told. A live demo creates emotional impact that slides cannot.
Rehearsal: Jobs rehearsed for days. Every transition, every demo, every word was practiced. The apparent effortlessness was the product of tremendous effort.
Simple visuals: Slides were minimalist—often a single image or a few words. The presenter was the content; slides were visual support.
These principles apply to technical presentations. You probably cannot match Jobs’s charisma, but you can have one clear theme, create narrative structure, show rather than tell, rehearse thoroughly, and simplify your slides.
Slide Design
One idea per slide: If you need multiple ideas, use multiple slides. Slides are free; audience confusion is expensive.
Minimal text: Slides are visual aids, not teleprompters. If you need notes, use speaker notes. The audience should listen to you, not read your slides.
Consistent design: Use a template. Inconsistent design is distracting and signals lack of attention to detail.
Readable at the back of the room: Use large fonts (30pt minimum for body text). Test readability by viewing your slides from across the room.
Meaningful visuals: Every diagram, chart, or image should convey information. Decorative images are noise.
Handling Questions
Questions reveal whether your presentation landed. Handle them well:
Listen completely: Do not formulate your answer while the question is still being asked. You may answer the wrong question.
Repeat or paraphrase: “If I understand correctly, you are asking about…” This ensures you address the actual question and lets others hear it.
Answer concisely: Long, rambling answers signal uncertainty or defensiveness. Get to the point.
It is acceptable to not know: “I do not know, but I will find out and follow up” is far better than guessing or deflecting.
Redirect when appropriate: “That is a great question that would take us off track—can we discuss offline?” Keep the presentation focused.
Watch for hidden feedback: Sometimes questions reveal that your main content was unclear. “So are you saying X or Y?” suggests your explanation was ambiguous.
Common Presentation Failures
Too much content: Presenters systematically overestimate what they can cover. Plan for less content than you think you need.
Reading slides: The audience can read. If you are just reading aloud, you are providing no value beyond the slides themselves.
No clear takeaway: Every presentation should leave the audience with something specific: an action, a decision, a new understanding. “That was interesting” is failure.
Ignoring time limits: Going over time disrespects the audience. Practice with a timer. Cut content rather than rushing.
Defensive about questions: Treating questions as attacks rather than engagement creates an adversarial dynamic. Questions mean people are interested.
Adapting Communication Style
Communication Dimensions
Effective communicators adjust multiple dimensions based on context:
Formality: Ranges from casual Slack message to formal executive briefing. Match the context and the relationship.
Detail level: Ranges from high-level summary to exhaustive specification. Give your audience what they need, not everything you know.
Directness: Ranges from subtle suggestion to blunt statement. Cultural context, power dynamics, and relationship quality all affect what is appropriate.
Channel: Synchronous (meeting, call) versus asynchronous (document, email). Choose based on urgency, complexity, and need for interaction.
When to Write vs. Talk
Some communication is better written; some is better spoken. Guidelines:
Write when:
- The information is complex and needs to be referenced later
- Readers need time to absorb and consider
- Documentation or audit trail is important
- You need to reach many people
- Time zones or schedules make synchronous communication difficult
Talk when:
- Nuance and back-and-forth are important
- The topic is sensitive or emotional
- You need to build relationship or trust
- A written thread is getting long or contentious
- Speed matters more than documentation
Do both when:
- You need both the depth of writing and the alignment of conversation
- Write first, then discuss: good for design reviews
- Talk first, then write: good for capturing decisions from discussions
Written Communication Principles
Front-load the important information: Busy readers may not finish. Put conclusions, decisions, and asks at the top.
Use structure: Headers, bullets, and numbered lists aid scanning. Dense paragraphs are hard to parse.
Be specific: “The system is slow” is less useful than “P99 latency increased from 200ms to 800ms after Tuesday’s deploy.”
Edit ruthlessly: First drafts are too long. Cut every word that does not serve the reader.
Read it aloud: You will catch awkward phrasing and unclear passages.
Communicating Uncertainty
AI engineers frequently must communicate uncertainty—about model behavior, predictions, or outcomes. Doing this effectively is challenging:
Quantify when possible: “About 80% accuracy” is better than “pretty accurate.” “Between 100ms and 500ms depending on load” is better than “fast.”
Distinguish types of uncertainty: Is this uncertainty because we do not have data? Because the system is inherently stochastic? Because we have not decided yet? The appropriate response depends on the type.
Provide ranges: “We expect 10-15% improvement” communicates uncertainty better than “We expect 12% improvement” (which implies false precision).
Explain what would reduce uncertainty: “We would have more confidence after running an A/B test for two weeks” guides action.
Do not let uncertainty become paralysis: At some point, you must make recommendations despite uncertainty. Frame them appropriately: “Given current information, I recommend X, with the caveat that Y could change this assessment.”
Worked Example: The Ship/No-Ship Decision
This is the single most important communication skill an AI engineer develops, so it is worth seeing concretely. Imagine you have built a fraud-detection model. Aggregate accuracy on the holdout set is 88%. A VP asks the question every stakeholder eventually asks: “Is it good enough to ship—yes or no?” Underneath the 88% is the fact that matters: the model performs well on the high-volume, low-risk majority but the segment that carries almost all of the financial downside—new accounts making large first transactions—has only a few hundred examples, and accuracy there is 71% with a 95% confidence interval of roughly 58% to 82%. You genuinely do not know whether the true number is closer to coin-flip or acceptable.
“The model is 88% accurate, which beats our 85% target. We’re good to ship.”
This is technically true and deeply misleading. It launders a single aggregate number into a yes, projects false precision (88%, not “around 88%”), and stays silent on the one segment where being wrong is expensive. When the new-account fraud losses show up three weeks later, the VP will remember that you said “we’re good to ship”—and they will be right to.
“Overall accuracy is 88%, above our 85% target, and I’d ship for the general population today. The decision hinges on one segment: new accounts making large first transactions. That’s about 2% of volume but the bulk of our fraud-loss exposure, and we have thin data there—accuracy is 71% with a wide confidence interval (roughly 58–82%). I can’t yet tell you whether that segment is genuinely acceptable or just looks okay by luck of a small sample.
Recommendation: ship to the general population now, and gate the new-account segment behind a manual review queue rather than auto-decisioning it. Two things would change this: (1) two weeks of shadow-mode data on new accounts would shrink that interval enough to decide, and (2) if the lower bound comes in above 80%, I’d remove the manual gate. If we instead ship the segment as-is today, we’re accepting an unknown that could plausibly be coin-flip on our highest-cost transactions.”
The good version is not longer because it hedges more—it is longer because it carries the information the decision actually requires. Notice what it does: it separates the confident part of the answer (general population) from the uncertain part (new accounts) instead of averaging them into one murky number; it quantifies the uncertainty with an interval rather than a point; it names why the uncertainty exists (small sample, not noise) so the listener knows it is reducible; it gives a real recommendation rather than retreating into “it depends”; and it states the explicit conditions that would flip the recommendation. That last move is what separates honest uncertainty from paralysis: the VP now has a decision and a clear picture of what would change it.
Difficult Conversations
Some technical conversations are inherently difficult. Handle them well:
Disagreeing with senior engineers: Lead with curiosity, not confrontation. “Help me understand the reasoning behind X—I am wondering about Y” invites dialogue. “X is wrong because Y” invites defensiveness.
Delivering bad news: Be direct but not brutal. “We will not make the deadline” is clearer than “There are some challenges with the timeline.” Follow with a plan: what can be done, what has changed, what you need.
Receiving criticism: Listen without defending. Ask clarifying questions. Thank the person for the feedback. Reflect before responding. If you disagree, explain why after you have fully understood their point.
Saying no: Be clear and provide reasoning. Offer alternatives when possible. “I cannot do X by Friday because of Y, but I could do Z, or do X by next Tuesday” is more helpful than just “No.”
Building Communication Skills
Deliberate Practice
Communication skills improve through deliberate practice, not just exposure. Deliberate practice requires:
Clear goals: What specific aspect are you trying to improve? “Write better” is too vague. “Write shorter sentences” or “Use more concrete examples” is actionable.
Feedback: You need external perspective to see your blind spots. Seek feedback on important communications. Record and review your presentations.
Repetition with reflection: Each iteration should incorporate lessons from previous attempts. Keep notes on what worked and what did not.
Specific Practices
Write every day: The more you write, the better you get. Internal documents, design proposals, and email all count.
Read good examples: Study well-written design documents, RFCs, and technical blog posts. Notice what works. Save examples for reference.
Practice presenting: Give more presentations, not fewer. Volume builds skill. Start with low-stakes contexts (team meetings) before high-stakes ones (executive briefings).
Record yourself: Video reveals habits you cannot see: filler words, pacing issues, closed body language. It is uncomfortable but invaluable.
Seek specific feedback: “How was my presentation?” invites vague praise. “Was my pacing too fast? Did the architecture section make sense?” invites useful feedback.
Learning from Failures
Communication failures are opportunities to learn. When communication goes wrong:
Analyze the failure: What happened? What did you intend? What did the receiver understand? Where did the gap occur?
Identify root causes: Was the channel wrong? Was there missing context? Did you misjudge the audience? Were you unclear?
Extract lessons: What would you do differently? Write it down. Review your notes before similar communications.
Follow up: If communication failed, repair it. Clarify, apologize if appropriate, and ensure the receiver now has what they need.
Summary
Technical communication is not a soft skill—it is the mechanism through which technical capability creates organizational impact. Engineers who communicate effectively have leverage: their insights influence decisions beyond their immediate work, their feedback shapes how others grow, and their writing becomes institutional knowledge that outlives their direct involvement.
The foundations of effective technical communication include:
Audience awareness: Understanding what your receiver needs, what they already know, and how they prefer to receive information. Meeting them where they are, not where you are.
Structured thinking: Using frameworks like the pyramid principle to organize information for clarity. Leading with conclusions, supporting with arguments, grounding in evidence.
Writing craft: Front-loading important information, using structure to aid scanning, editing ruthlessly, and defeating the curse of knowledge through concrete examples and explicit context.
Design documents and RFCs: The primary vehicles for scaling technical influence. Well-written documents align stakeholders, clarify thinking, enable feedback before investment, and create institutional memory.
Code review as teaching: Reviews are conversations, not inspections. Effective review comments explain issues, suggest solutions, distinguish blocking from non-blocking feedback, and include encouragement.
Presentations: Different from documents in structure and purpose. Linear, transient, and suited for narrative and persuasion. Require rehearsal, audience adaptation, and simple visuals.
Adaptability: Adjusting formality, detail level, directness, and channel based on context and audience. No single style works for all situations.
Communication skills are learnable through deliberate practice. Write often, seek feedback, study good examples, and analyze failures. Over time, clear communication becomes habitual rather than effortful.
Practical Exercises
Design document rewrite: Find a design document you have written (or a public one). Identify three ways it could better apply the principles in this chapter. Rewrite the summary and one major section.
Audience translation: Take a technical concept you know well (a system you have built, an algorithm you understand). Write three one-paragraph explanations: one for a peer engineer, one for a product manager, one for an executive. Compare them—what changed?
Code review analysis: Look at your last ten code review comments. Categorize them by type (question, suggestion, concern, nit, praise). What patterns do you see? Are you appropriately labeling blocking versus non-blocking?
Presentation rehearsal: For your next presentation, record yourself rehearsing. Watch the recording. Identify three specific things to improve.
Communication failure postmortem: Think of a recent communication that did not go as intended. Write a brief analysis: what happened, what you intended, where the gap occurred, and what you would do differently.
Self-Assessment Checkpoint
Conceptual Questions
Q1. [IC2] What is the “pyramid principle” in technical writing? How does it differ from how we naturally construct explanations?
Answer
The pyramid principle (Barbara Minto): Lead with the conclusion, then provide supporting arguments, then supporting details. Structure: Main point → Key arguments → Evidence.
Natural tendency: Build up to the conclusion chronologically or by discovery order. “First I tried X, then I noticed Y, which led me to Z, and finally I concluded…”
Why pyramid works better: (1) Readers can stop when they have enough info. (2) Busy readers get the key point even if interrupted. (3) Easier to skim—structure reveals importance. (4) Reduces “so what?” questions—you answer upfront.
Application to technical docs: Start with “We should do X because of Y” not “Let me explain the context…” The context supports the recommendation, not vice versa.Q2. [IC2] What makes a code review comment effective? What makes one counterproductive?
Answer
Effective comments: (1) Specific: Point to exact location and concrete issue. (2) Actionable: Clear what change is requested. (3) Explain why: “This could cause race condition because…” not just “This is wrong.” (4) Calibrated: Distinguish blocking issues from suggestions/nits. (5) Respectful: Question the code, not the person.
Counterproductive comments: (1) Vague: “This seems wrong” without explanation. (2) Personal: “Why would you do this?” (3) Nitpicking without labeling: Many style preferences presented as requirements. (4) Rewriting style: “I would have done it differently” without defect. (5) Drive-by negativity: Issues without solutions or discussion.
Best practice: Use prefixes. “Blocking: This leaks PII.” “Suggestion: Consider using X for readability.” “Nit: Typo in comment.” “Question: Why did you choose this approach?”Q3. [Senior] How should you structure a technical presentation for a mixed audience (executives, PMs, and engineers in the same room)?
Answer
Structure: Layered depth with clear transitions.
Opening (2-3 min): Business context everyone understands. “We’re here to decide whether to invest $X in Y, which could save/earn $Z.”
Executive summary (5-10 min): Recommendation, key tradeoffs, timeline, resources needed. Executives can leave after this with full picture.
PM details (10-15 min): User impact, feature implications, success metrics, rollout plan. Engineers stay engaged; executives can tune out.
Technical deep dive (10-20 min): Architecture, implementation approach, risks, dependencies. Label this section clearly so non-technical attendees can check out.
Q&A: Be ready to answer at any depth. Match depth to questioner.
Visual design: Summary slides first, detailed slides as appendix. Never apologize “this is technical”—instead, signal transitions: “The next section is for those interested in implementation details.”Q4. [Senior] You need to tell stakeholders that a project will be 3 months late. How do you structure this communication?
Answer
Structure: Bad news, why, what’s next, what you need.
Don’t: Bury the lead. “As you know, the project involves many complexities, and we’ve encountered some challenges…” They’ll tune out before the point.
Do: Lead with news, show you have a plan.
“Project X will ship in September instead of June. Here’s what happened and our path forward.
Root cause: [Specific, honest—not excuses, not blame]
Current state: We’ve completed Y%, with Z remaining.
New timeline: [Specific milestones with dates]
What we’re doing differently: [Specific changes to prevent recurrence]
What I need from you: [Resources, decisions, support]
Next check-in: [When you’ll update]”
Key principles: (1) Own the miss—don’t blame external factors unless truly unavoidable. (2) Show you understand impact—don’t minimize. (3) Have a plan—don’t just deliver bad news. (4) Be specific about asks—vague “support” isn’t actionable.Q5. [Staff] How do you write a design document that gets genuine feedback rather than rubber-stamp approval?
Answer
Common failure: Document is too polished, too complete, presented as fait accompli. Reviewers feel feedback is unwelcome or futile.
Techniques for genuine engagement:
Explicit alternatives: “I considered approaches A, B, and C. I’m recommending B because… but I could be wrong about X.”
Open questions: “I’m uncertain about Y—what do others think?” Genuine uncertainty, not rhetorical.
Call out risks: “This approach has risk Z. Here’s my mitigation, but I’d appreciate review.”
Request specific feedback: “I particularly want feedback on the consistency tradeoffs in section 3.” Vague “PTAL” gets vague responses.
Staged review: Share early drafts with “still forming opinion on X”—not final drafts that discourage pushback.
Devil’s advocate: “Argue against this proposal” explicitly invited.
Multiple options doc: Sometimes present 2-3 options without recommendation. Let discussion determine direction.
Spot the Problem
Problem 1. [IC2] A design document summary:
“This document describes the implementation of a new caching layer for the recommendation service. We will use Redis with a 15-minute TTL. The cache will be deployed across three regions.”
What’s missing?
Answer
Missing: (1) Why: No business problem or motivation. Why do we need caching? What problem does it solve? (2) Impact: No expected outcome. “Reduce latency from X to Y” or “save $Z/month on compute.” (3) Tradeoffs: No mention of alternatives considered or downsides of this approach. (4) Scope: No indication of what this doc doesn’t cover. (5) Audience signal: No indication who should read this or what decisions it enables.
Better summary: “Recommendation service latency increased 3x after launch (p99: 800ms → 2.4s), impacting user engagement. This document proposes a Redis caching layer expected to reduce p99 to <500ms by caching 60% of recommendations.
We evaluated Redis, Memcached, and application-level caching. Redis was chosen for its persistence and data structure support, with tradeoffs discussed in Section 4.
Key decision needed: Approve 3-region deployment budget ($X/month) by [date].”Problem 2. [Senior] A code review comment:
“I don’t think this is the right approach. Have you considered using the pattern we discussed last week? This feels over-engineered for what we need.”
What’s wrong with this feedback?
Answer
Issues: (1) Vague: “Not the right approach” without specifics. What’s wrong? (2) Assumes context: “Pattern we discussed last week”—not in the code review, may be forgotten or misremembered. (3) Subjective: “Feels over-engineered” is opinion without evidence. (4) Not actionable: What should the author do differently? (5) Tone: Could feel dismissive, even if not intended.
Better version: “Concern: This adds three abstraction layers for what appears to be a single use case. I’d suggest:
Option 1: Use the factory pattern from our auth service (link to example). It handles the same dispatch logic with less indirection.
Option 2: If we expect multiple implementations soon (do we?), keep this structure but simplify the intermediate layer.
Could you clarify the expected future use cases? If this is the only implementation planned for 6+ months, Option 1 might be simpler to maintain. Not blocking—happy to discuss.”Problem 3. [Staff] An engineer’s presentation to leadership has these slides:
Slide 1: “Improving Search Relevance” Slide 2: [Detailed architecture diagram with 15 components] Slide 3: “Embedding Model Comparison” [Table with 20 rows of metrics] Slide 4: “Implementation Timeline” [12-month Gantt chart] Slide 5: “Questions?”
What would you coach them to change?
Answer
Problems: (1) No executive summary—jumps to architecture without business context. (2) Too detailed too fast—architecture diagram belongs later or in appendix. (3) Metrics without meaning—20-row table is unreadable and unexplained. (4) Timeline without milestones—Gantt charts confuse leadership; they want “when will we see value?” (5) No ask—what decision or action is requested?
Better structure:
Slide 1: “Improving Search Relevance: Proposal for $X investment to increase conversion by Y%” (Title states purpose and stakes)
Slide 2: “The Problem” - 3 bullets on current state, one metric showing pain.
Slide 3: “The Proposal” - One sentence recommendation, expected outcome, cost.
Slide 4: “Timeline & Milestones” - 3-4 key dates, what’s delivered at each.
Slide 5: “Decision Requested” - What you need from this audience.
Appendix: Architecture diagram, metrics table, detailed timeline for those who want depth.
Key coaching: “What’s the one thing you want them to remember? Lead with that.”Design Exercises
Exercise 1. [Senior] You’re writing an RFC for a significant architectural change: migrating from a monolithic API to microservices. Design the RFC structure and outline key sections. Consider: how do you present alternatives fairly, how do you quantify tradeoffs, and how do you get genuine debate rather than premature consensus?
Guidance
RFC structure:
Summary (1 paragraph): What change, why now, expected outcome.
Motivation: (a) Current problems with evidence. (b) Business impact of problems. (c) Why alternative solutions don’t work.
Proposal: (a) Target architecture (diagram). (b) Migration approach (phased). (c) Key technical decisions within proposal.
Alternatives considered: At least 2-3 genuine alternatives with fair assessment. Include “do nothing” as baseline. For each: what it would look like, pros, cons, why not recommended.
Tradeoffs: (a) What we’re giving up. (b) New risks introduced. (c) Operational complexity changes.
Quantified comparison: Table comparing options on key dimensions (cost, latency, velocity, operational burden). Use rough estimates, not false precision.
Migration plan: Phases, rollback strategy, success criteria per phase.
Open questions: Genuine uncertainties where you want input. Number them for easy reference.
Appendix: Detailed calculations, benchmarks, prior art.
Exercise 2. [Staff] A critical production incident occurred. You need to write the post-incident review that will be shared with engineering leadership and used to prevent recurrence. Design the document structure and identify common pitfalls in incident communication.
Guidance
Document structure:
Executive summary: (a) What happened (1-2 sentences). (b) Impact (duration, users affected, revenue impact). (c) Root cause (1 sentence). (d) Status (resolved, mitigated, monitoring).
Timeline: Factual chronology. When detected, who responded, key actions, when resolved. Use timestamps.
Impact analysis: (a) Quantified impact (requests failed, revenue lost, SLA breach). (b) Customer impact (who was affected, how). (c) Internal impact (engineer hours, reputational).
Root cause analysis: (a) Technical cause (the bug/failure). (b) Contributing factors (why wasn’t it caught earlier). (c) 5 Whys or similar structured analysis.
What went well: Explicitly note effective response elements.
What could improve: Process gaps, detection delays, communication issues.
Action items: Specific, assigned, with deadlines. Distinguish “prevent recurrence” from “improve response.”
Common pitfalls: (1) Blame: “Engineer X made a mistake” vs. “System allowed mistake to reach production.” (2) Vagueness: “Improve monitoring” vs. “Add alert for X threshold by Y date (owner: Z).” (3) Over-promising: 47 action items that will never be completed. Prioritize ruthlessly. (4) Under-sharing: Hiding embarrassing details reduces organizational learning. (5) Defensiveness: Explaining why it wasn’t your fault, rather than how to prevent recurrence.
Tone: Blameless but accountable. Focus on systems, not individuals. Honest about failures. Forward-looking on solutions.Connections to Other Chapters
Technical communication skills apply throughout AI engineering work:
Chapter 22 (Project Ownership & Delivery): How communication supports project execution, stakeholder management, and delivery.
Chapter 23 (Technical Decision Making): Design documents and RFCs as decision-making tools, plus the ADR format for recording decisions.
Chapter 26 (Cross-Team Technical Leadership): Communication skills for influencing across organizational boundaries.
Chapter 24 (Mentorship Foundations): Communication techniques for teaching and giving feedback.
Architecture Decision Records (Appendix G): Templates and examples for the ADR format discussed in this chapter.
Further Reading
Essential
- Minto, “The Pyramid Principle” - Foundational text on structured business writing.
- Zinsser, “On Writing Well” - Classic guide to clear, concise writing.
- Tufte, “The Visual Display of Quantitative Information” - Definitive work on data visualization.
Deep Dives
- Sadowski et al. (2018), “Modern Code Review at Google” - Detailed study of code review at scale.
- Patterson et al., “Crucial Conversations” - Framework for high-stakes discussions.
Practical Resources
- Duarte, “Resonate” - Presentation design and storytelling for impact.
Comment Types
Labeling comment types helps authors understand your intent:
[Question]: Genuine request for understanding. Not a criticism—you want to learn something.
[Suggestion]: An idea for improvement that is not required. The author may take it or leave it.
[Concern]: Something you think should be addressed. May be blocking or non-blocking.
[Nit]: Minor style or preference issue. Explicitly not blocking.
[Praise]: Recognition of something done well. Important for morale and learning.
Additionally, indicate blocking status:
Blocking: This must be addressed before approval. Reserve for real issues—correctness, security, significant design problems.
Non-blocking: Worth considering but not required for merge. Author can use their judgment.