Efficiently written documents are efficient communication: they make problems clear, tradeoffs explicit, and decisions easy to act on. Some companies (Amazon is the obvious example) institutionalized this: narratives over slides, clarity over performative alignment. This post is a practical framework and checklist you can apply to your next design doc, solution proposal, incident write-up, or business memo.
Writing forces you to structure and stress-test ideas before sharing them. Verbal explanations let you skip gaps - a written document cannot hide them. Drafting even a one-pager surfaces flawed assumptions, missing data, and logical gaps that slides conceal. Documents invite scrutiny; slides push information. A well-written document reduces back-and-forth and creates a lasting reference. Bezos: there is no way to write a narratively structured memo and not have clear thinking.
Keep sentences under 30 words. Aim for 20 or fewer. Each sentence carries exactly one message. When you find yourself writing a sentence with two independent clauses joined by “and” or “but,” split it. Long sentences hide weak reasoning behind syntactic complexity.
Replace adjectives with data. Vague qualifiers give readers nothing to act on. Precise numbers give them everything they need.
For direct questions, give one of four answers — yes, no, a number, or “I don’t know, and will follow up by [date].”
Writing examples: ❌ “bad” -> ✅ “good”
Documents outlive their context. Relative time references decay the moment a document is saved. A new team member, a cross-functional partner, or a future reader should understand your document without a decoder ring. Never assume shared context — spell out every acronym and unit on first use.
Time references:
Acronyms and units:
Shared context:
Most documents fail the same way: vague claims that hide behind adjectives, passive sentences that obscure ownership, and logic that jumps between unrelated topics. This checklist eliminates those failure modes before they reach your reader.
Eliminate vague language: No weasel words — might, could, some argue, often, significantly. No peacock words — cutting-edge, innovative, best-in-class, state-of-the-art. Every claim backed by data or a cited source.
Tighten the writing: Each sentence under 30 words, one message each. Active voice throughout. Acronyms defined on first use. No relative time references.
Check the logic: Each paragraph makes one argument. Paragraphs flow — topic sentence, evidence, link to next. The document answers a clear question or drives a specific decision. If you cannot state that question in one sentence, revise until you can.
☑ No weasel words — qualifiers that hedge claims without adding information:
☑ No peacock words — claims of superiority with no supporting data:
☑ Every claim backed by data or a cited source:
☑ Each sentence under 30 words, one message each:
☑ Active voice throughout:
☑ No relative time references:
☑ Each paragraph makes one argument:
☑ The document answers a clear question or drives a specific decision:
For most situations, a one-pager is the right tool: one problem, one proposed solution, key supporting data, one clear next step with an owner. Use appendices for tables, graphs, or raw data - keep the main narrative clean and scannable. Reserve longer formats (three to six pages) for high-stakes decisions: architecture changes, research proposals, incident post-mortems, or investment cases.
When the decision is complex enough to warrant a longer document, use a fixed structure - introduction, goals, tenets, state of the business, lessons learned, and strategic priorities. A predictable format lets readers engage with ideas rather than decode structure. See “Appendix B: Minimal Decision Document” as example.
Clear writing is a force multiplier for any technical team. It replaces meetings, accelerates decisions, and scales institutional knowledge across time zones and org changes. You do not need a company-wide mandate to start. Apply this framework to your next design doc, incident report, or proposal email.
Most alignment problems are undocumented decisions. Fix the writing, and the alignment follows.
Hedging qualifiers might, may, could, would, should, can, possibly, perhaps, probably, potentially, presumably, apparently, seemingly, ostensibly
Vague frequency often, frequently, sometimes, occasionally, generally, usually, typically, commonly, regularly, largely, mostly, broadly, in many cases, in some cases
Vague quantity some, many, few, several, various, numerous, certain, a number of, a variety of, a range of, most, majority, minority
Vague magnitude significant, substantial, considerable, notable, major, minor, marginal, meaningful, material, meaningful, moderate, extensive, limited
Vague improvement better, worse, faster, slower, cheaper, more expensive, higher, lower, increased, decreased, improved, degraded — (any comparative without a reference point or number)
Epistemic hedges it is believed, it is thought, it is felt, it seems, it appears, evidence suggests, data indicates, research shows — (without a cited source)
Attribution deflection some argue, some say, many believe, experts suggest, industry thinks, people feel, stakeholders expect, the team feels
Vague time recently, soon, shortly, in the near future, going forward, eventually, in due course, at some point, historically, traditionally, in the past
Filler intensifiers very, quite, rather, fairly, pretty, somewhat, relatively, extremely, incredibly, highly, deeply, truly, really, essentially, basically, virtually, effectively, largely
Most decisions fail not in execution but in documentation — the reasoning is never written down, options are never compared, and six months later nobody remembers why the call was made. A decision document does not need to be long. It needs to be complete.
Decision required: One sentence stating exactly what needs to be approved or chosen, and by when. “Approve migration from self-hosted Elasticsearch to Elastic Cloud by Mar 31, 2026.”
Context: What changed that makes this decision necessary now. Two to three sentences maximum. “Elasticsearch 7.x reaches end-of-life on Aug 31, 2026. Our current cluster requires a $40K hardware refresh to remain on-prem. Elastic Cloud eliminates that capital expenditure.”
Options considered: List every option evaluated, including the status quo.
Data and tradeoffs: The two or three numbers that actually drive the decision. “Elastic Cloud costs $18K/year vs. $40K upfront for hardware refresh. Migration requires 3 weeks of engineering time. Downtime risk: under 4 hours with blue-green cutover.”
Recommendation: One sentence, no hedging. “Migrate to Elastic Cloud. Lower total cost, eliminates operational burden, and meets the Aug 2026 EOL deadline with margin.”
Owner and date: Who is accountable, and when the decision expires. “Owner: Platform Engineering Lead. Decision required by Mar 1, 2026.”