本文由 AI 分析生成
建立時間： 2026-03-28 來源： https://www.seangoedecke.com/technical-communication/
Summary
Sean Goedecke’s November 2025 essay arguing that the biggest mistake engineers make in technical writing is expecting too much from it. Almost none of your readers will pay careful attention; the correct mental model is “almost all of them will skim.” The fix is to write less, frontload everything, and accept that technical writing communicates very simple points to large audiences or complex points to tiny audiences.
Sean Goedecke 2025 年 11 月的文章，認為工程師在技術寫作中最大的錯誤是期望太高。幾乎沒有讀者會仔細閱讀；正確的心智模型是「幾乎所有人都會略讀」。解決方法是寫得更少、把最重要的信息放在開頭，並接受技術寫作只能向大受眾傳達非常簡單的觀點，或向極小受眾傳達複雜觀點。
Key Points
- Primary rule: almost no readers will pay much attention — read first sentence, skim the next, stop or skim the rest
- Write as little as possible: if one sentence communicates the idea, use one sentence
- Deliberately omit subtle details: unlike code (every character matters to the compiler), each additional point you make to humans consumes limited attention budget
- Frontload everything: get your point in the very first sentence, or better yet, in the title
- What technical writing cannot do: transplant your understanding into someone’s head; get everyone on the same page; fix disagreement or confusion in large organizations
- What it can do: communicate a very simple point to a broad audience; communicate a reasonably complex point to a tiny audience (ADR effective audience: often single digits or 2 people)
- The key difference from code: code has 1:1 attention from the compiler; human readers have a limited attention budget shared across many demands
- Thinking clearly comes first: you can’t condense if you don’t understand; the writing problem is often a clarity-of-thought problem
Insights
The “lower your expectations” frame is unusually honest and immediately actionable. The ADR example is particularly grounding: an architectural decision record that “goes into many subtle details” may effectively be written for 2 people — the author and one other engineer with the requisite context. Designing for that audience, not a broad imagined one, produces much better writing. The comparison to LLMs in a footnote (attention budget ≈ token window) is apt. The most durable principle: in large organizations, “the baseline level of technical confusion is so high that communicating even obvious things is high-leverage.”
Connections
Raw Excerpt
The biggest mistake engineers make in their technical writing is setting their expectations too high. They try to communicate in too much detail and end up failing to communicate anything at all: either because readers are checked out by the time they arrive at the key point, or because they’ve simply assumed too much background technical knowledge.