I have written hundreds of technical documents over the years — RFCs, architecture decision records, strategy docs, one-pagers, post-mortems. Most of them were fine. Some of them changed the direction of entire product lines. And a shameful number of them were completely ignored.
The difference between a document that gathers dust and one that moves an organization is almost never the technical content. It is the framing. Engineers write for engineers — we default to thoroughness, precision, and technical depth. But the people making funding and priority decisions are directors, VPs, and C-suite leaders who have not had time to read past the first page. If we want technical decisions to be informed by technical reality, we need to meet decision-makers where they are.
“Being a senior engineer is not just about solving hard technical problems. It’s about making sure the right problems get solved.” — Tanya Reilly, The Staff Engineer’s Path
Why Most Technical Documents Fail
The same failure patterns appear again and again:
| Failure Pattern | What It Looks Like | Why It Kills Your Document |
|---|
| Too long | 15-page RFC when a 2-page one-pager would do | Length signals you have not distilled your thinking. Readers give up. |
| Too technical | Deep implementation details before establishing stakes | Your VP does not need the Redis eviction policy — they need to know it will cause outages in six months. |
| No business context | Brilliant proposal with zero connection to company goals | If you cannot tie your recommendation to revenue, customer experience, or risk, it will not survive a priority discussion. |
| No clear recommendation | Three options presented with equal weight | That is abdicating your job. You are the technical expert — make a call and defend it. |
If your document requires more than 15 minutes to read and understand the core argument, it is too long for a leadership audience. Write the short version first. Attach the long version as an appendix for engineers who want depth.
| Section | Purpose | Length |
|---|
| Problem | What is broken, at risk, or missing — stated in business terms with data (incident frequency, customer complaints, developer hours wasted) | 2-3 sentences |
| Context | Why now? What changed? What happens if we do nothing? This is your “burning platform.” | 2-3 sentences |
| Options Considered | A comparison table of options including pros, cons, effort (S/M/L), and risk (Low/Med/High). Always include “Do nothing” as an explicit option. | Table format |
| Recommendation | Your pick and a 1-2 sentence justification tied to business outcomes | 1-2 sentences |
| What We Need | The specific ask — budget, headcount, priority slot, timeline, decision-by date | 1-2 sentences |
Write the “Recommendation” section first. If you cannot state your recommendation clearly in two sentences, you are not ready to write the document. Everything else exists to support that recommendation.
Writing for Different Audiences
The same technical decision needs different framing for different people. Think of it as translation, not dumbing down.
| Audience | They Care About | Document Style | Detail Level |
|---|
| Engineers | How it works, trade-offs, migration path | RFC or ADR | High — show the design |
| Engineering Managers | Timeline, team impact, hiring needs | One-pager with staffing section | Medium — focus on execution |
| Directors | Portfolio fit, cross-team dependencies, risk | One-pager with org context | Low-medium — focus on strategy |
| VPs and C-suite | Business impact, investment required, competitive position | Executive summary plus appendix | Low — focus on outcomes |
In a small engineering team, one document often serves all audiences because the CTO reads the full RFC. In a large organization with hundreds of engineers, you routinely write three versions of the same proposal. Scale changes communication requirements dramatically.
The “So What?” Test
Before sending any document, read every section and ask: “So what?” If you cannot answer that question in terms the reader cares about, the section needs rewriting or cutting.
| Version | Reaction |
|---|
| ”We should migrate from REST to GraphQL.” | Leadership asks “Why should I care?” and moves to the next agenda item. |
| ”Migrating to GraphQL would reduce mobile app data transfer by 60%, improving load times for our fastest-growing market segment and reducing CDN costs by approximately $40K per year.” | Leadership leans forward and asks about the timeline. |
Visual Communication
Engineers underuse visual communication. A well-designed diagram conveys in 30 seconds what takes three paragraphs to explain in text.
| Visual Type | When to Use It |
|---|
| Architecture diagram | Show system boundaries, data flow, and the specific components being changed — highlight the delta, not the whole system |
| Before/after comparison | Side-by-side of current state vs proposed state for immediate visual clarity |
| Timeline diagram | For migrations — show phases with clear milestones and rollback points |
| Dependency graph | When the argument is “this is too coupled,” show it visually instead of explaining it in prose |
Put your most important diagram within the first half-page of the document. Busy readers scan visually before they read text. A clear architecture diagram at the top hooks a reader who would otherwise skim past your carefully written paragraphs.
