English
The ability to write clearly is among the highest-leverage skills an engineer can develop, and it is consistently undervalued by people who entered the field to work with machines rather than words. The undervaluation is a mistake, and the reason is structural: an engineer’s influence scales with their ability to communicate, and beyond a certain level of seniority, writing is the primary medium of influence. A design that is not clearly written is not seriously considered. A proposal that is not clearly argued does not persuade. A decision whose reasoning is not clearly recorded is relitigated endlessly. The engineers whose ideas shape what their organizations build are, with rare exceptions, the ones who can write those ideas down clearly enough that others understand, evaluate, and adopt them. Technical skill that cannot be communicated is technical skill that influences only what its holder can build alone.
Writing is also a tool for thinking, not merely for communicating thoughts already formed. The discipline of writing something down — a design, an argument, an explanation — forces a precision that thinking alone permits one to avoid. Ideas that seem clear in the head reveal their gaps, contradictions, and vagueness when one tries to write them precisely. This is why writing a design document often changes the design: the act of writing exposes the problems that hand-waving concealed. The engineer who writes does not merely record their thinking; they improve it, because writing is where loose thinking is caught and corrected. The practitioner who avoids writing avoids the discipline that would sharpen their thinking, and their thinking is the worse for it.
This section addresses the genres of technical writing an engineer produces — documentation, design documents, proposals, commit messages and pull request descriptions, incident reports, explanatory writing — and the principles that make technical writing effective across all of them. It is the output counterpart to reading technical literature (§8.7): the same precision and structure that make literature worth reading are what the writer must produce. And it must address how AI writing assistance changes the activity, which it does in a way that is genuinely useful and genuinely dangerous, because writing is thinking, and outsourcing the writing can mean outsourcing the thinking.
Prerequisites: Reading technical literature (§8.7) — you write better having read good technical writing and felt the cost of bad. The domain knowledge of whatever you are writing about. General writing ability, which technical writing specializes rather than replaces.
The Shape of the Skill: Writing for the Reader, to Think Clearly
Technical writing is the craft of conveying technical information clearly to a specific reader for a specific purpose, and its two defining characteristics — that it serves a reader, and that it sharpens the writer’s thinking — organize everything about the skill.
The first characteristic is that technical writing is reader-centered, more so than most other writing. The reader of a technical document is trying to accomplish something — understand a system, evaluate a proposal, implement against a specification, fix a problem — and the writing succeeds or fails by whether it helps them accomplish it. This is a sharper criterion than “good writing” in the literary sense: technical writing is good if the reader, after reading, can do what they came to do. This reader-centered standard implies the principles of the craft: know who the reader is and what they need, structure the document so they can find what they need, say things in the order that builds their understanding, be precise so they are not misled, and be concise so their time is not wasted. Every principle of technical writing is an elaboration of serving the reader’s purpose.
The second characteristic is that writing is a thinking tool. The novice imagines that writing is the transcription of fully-formed thoughts: you think the thing, then you write it down. The experienced writer knows that writing is where the thinking gets finished, because the precision that writing demands exposes the gaps that thinking tolerated. Writing a design document reveals that the design has an unhandled case; writing an argument reveals that a step does not follow; writing an explanation reveals that you did not understand the thing as well as you believed. This is not a flaw in one’s thinking or writing; it is the mechanism by which writing improves thinking, and the writer who embraces it — who writes precisely in order to find the gaps, and treats the discovered gaps as the point rather than an annoyance — uses writing to think better, not just to record thought.
Technical writing is best understood through its genres, because each genre has a purpose that determines its form. Documentation serves a reader trying to use a system, and its form follows the layered structure of §8.7 (overview, tutorial, reference). The design document serves readers evaluating and later understanding a technical decision, and its form presents the problem, the proposed solution, the alternatives considered, and the reasoning. The proposal serves readers deciding whether to do something, and its form makes the case. The commit message and pull request description serve the future reader recovering intent (§8.3, §8.5), and their form explains the why. The incident report serves the organization learning from a failure (§4.10), and its form is the blameless analysis of what happened and why. Each genre’s form is determined by its reader’s purpose, and knowing the genre means knowing what its reader needs. The recent development that bears on the skill is AI writing assistance, addressed below, which can draft any of these genres and thereby tempts the writer to skip the thinking that writing them is supposed to produce.
Clarity, Structure, and the Genres of Technical Writing
The Principles of Clear Technical Writing
Clear technical writing rests on a small set of principles that apply across all the genres, each serving the reader’s ability to extract what they need.
Know the reader and write for them. The same content must be written differently for different readers: a design document for the engineering team assumes knowledge that a proposal for executives cannot. The writer who has identified their reader — what they know, what they need, why they are reading — can pitch the writing correctly; the writer who has not produces writing that is over the head of some readers and beneath others, serving neither. The first question of any technical document is who it is for, and the answer shapes everything else.
Lead with the conclusion. Technical readers are usually reading to extract specific information, not to be taken on a journey, and they should not have to read to the end to find the point. The structure that serves them puts the conclusion first — the recommendation, the result, the answer — and then provides the supporting detail for those who need it. This is the inverse of the narrative structure (build-up to a conclusion) that other writing uses, and it is correct for technical writing because the reader wants the answer and then, if they need it, the justification. The abstract of a paper, the summary of a design document, the conclusion-first structure of a good technical email — all serve the reader who needs the point quickly.
Structure for navigation. Technical documents are navigated, not read linearly: readers scan for the section they need, jump to the relevant part, and read closely only what concerns them. Writing that serves this provides the structure to navigate — informative headings, a logical organization, summaries that let readers decide what to read closely — so the reader can find their way. A document that must be read linearly to be understood fails the reader who needs only part of it, which is most readers of most technical documents.
Be precise and be concise, which are compatible and both serve the reader. Precision means saying exactly what is true, without the vagueness that forces the reader to guess at the meaning — naming things exactly, stating quantities exactly, distinguishing what is certain from what is conjectured. Concision means saying it in as few words as serve the purpose, without the padding that wastes the reader’s time and buries the content. The two together produce writing that conveys the most information for the least reading effort, which is the efficiency that technical readers need. Most technical writing is improved by cutting: the first draft is too long, and revising it down to the essential — removing the redundancy, the throat-clearing, the unnecessary qualification — improves it.
The Design Document
The design document is the genre where technical writing most directly shapes engineering, and writing one well is a distinct and valuable skill. A design document proposes a technical approach to a problem, with enough detail and reasoning that others can evaluate it, and enough record that future engineers can understand why the system is the way it is. It is the artifact through which significant technical decisions are made and remembered.
The structure of an effective design document follows the reader’s evaluation: the problem (what are we solving, and why does it matter?), the proposed solution (what is the approach?), the alternatives considered (what else could we do, and why is the proposal better?), the tradeoffs and risks (what does this cost, what could go wrong?), and the details necessary to evaluate and implement. The alternatives section is what distinguishes a design document from an advocacy piece: presenting the alternatives fairly, and explaining why the proposed approach is preferred, demonstrates that the decision was made with judgment rather than by default, and it is what lets reviewers evaluate the decision rather than merely accept it. The design document that presents only the chosen approach, with no alternatives, is not a design document but a justification, and it deprives reviewers of the ability to evaluate the choice.
The discipline of writing the design document before building is where its value as a thinking tool is greatest. Writing the design forces the consideration of the cases, the alternatives, the failure modes, and the tradeoffs before they are encountered in code, when they are cheap to address. The design document that reveals, in the writing, that the proposed approach has a fatal flaw has done its job — it caught the flaw before it was built. This is why the practice of writing design documents for significant work, and reviewing them before building, is one of the higher-leverage engineering practices: it moves the discovery of problems earlier, where they are cheaper, and it produces the record that makes the decision understandable later.
The Smaller Genres: Commits, Pull Requests, Incidents, and Documentation
The smaller genres are written far more often than design documents, and their cumulative effect on a codebase and an organization is large. The commit message and pull request description (§8.5) serve the future reader recovering why a change was made; written well, they make the history a usable record, and written badly (“fix”, “update”), they throw away the only chance to record the reasoning. The discipline is to explain the why — the motivation and context that the code itself does not contain — concisely but completely enough that the future reader understands.
The incident report (§4.10) serves the organization’s learning from failure, and its form is the blameless analysis: what happened, in what sequence, why (root cause, not blame), and what will change to prevent recurrence. The writing principles that matter here are precision (exactly what happened, in what order) and the blameless framing (focusing on the systemic causes rather than individual fault), which is what makes the report a learning tool rather than a punishment and what makes people willing to write honest ones.
Documentation serves the reader trying to use a system, and writing it well follows the layered structure (§8.7): the conceptual overview that conveys the model, the tutorial that gets the reader started, the reference that documents the details precisely. The most common documentation failures are writing only one layer (reference with no conceptual overview, so the reader can find every function but not understand the model), and writing for the author rather than the reader (assuming the context the author has and the reader lacks). Good documentation is written from the reader’s position of not yet understanding the system, which is the position the author has to deliberately reconstruct because they no longer occupy it.
AI Writing Assistance: Drafting Versus Thinking
AI writing assistance can draft any technical genre — generate a design document from a description, write a commit message from a diff, produce documentation from code, draft an explanation of a concept. For the mechanical parts of writing, this is genuinely useful: it removes the friction of producing a first draft, suggests phrasings, drafts the routine documentation that no one wants to write, and helps writers whose first language is not the document’s language produce fluent prose. Used for these purposes, it is a real productivity aid.
The danger is specific and follows from writing being a thinking tool. If the value of writing a design document is largely in the thinking that writing it forces — the discovery of the unhandled cases, the flawed steps, the gaps in understanding — then having an AI write the design document skips exactly the thinking that was the point. The AI produces a fluent document that may conceal, rather than expose, the gaps that writing it yourself would have revealed, because the AI does not have your specific understanding of the problem and cannot do the thinking that needed to be done. The writer who outsources the design document to AI gets a document and loses the thinking, which is the worse trade than it appears, because the thinking was the valuable part.
The productive relationship distinguishes the writing where the thinking matters from the writing where it does not. For routine documentation, boilerplate, and mechanical drafting, AI assistance is a straightforward win — the thinking is minimal and the friction-reduction is real. For the writing that is thinking — the design document for a hard problem, the argument for a significant decision, the explanation that requires understanding the thing deeply — the writer should do the thinking, which means doing enough of the writing to force the thinking, using AI to polish and assist rather than to replace the cognitive work. And in all cases, the writer remains responsible for the content: AI-drafted technical writing can be confidently wrong, can state things that are not true, and must be verified by a writer who understands the material. The skill in the AI era is knowing which writing to delegate and which to do, and maintaining the writing-as-thinking practice where it matters even as AI makes it easy to skip.
What Changes With Mastery
The ability to write clearly changes an engineer’s influence and the quality of their thinking.
The first change is influence that scales beyond what one can build alone. The engineer who writes clearly can propose designs that get adopted, make arguments that persuade, and record decisions that endure — their ideas shape what the organization builds, not just what they build themselves. As seniority increases and the work shifts from building to directing, this writing-mediated influence becomes the primary form of impact, and the engineer who can write has it while the engineer who cannot is limited to individual contribution regardless of the quality of their ideas.
The second change is sharper thinking, from the discipline of writing precisely. The engineer who writes their designs, arguments, and explanations subjects their thinking to the precision that writing demands, and catches the gaps and errors that thinking alone tolerates. Their thinking is better because it has been written, and the habit of writing to think — using the design document to find the design’s flaws, using the written argument to test its logic — is a thinking discipline that improves the quality of their technical judgment.
The third change is a more effective and more humane organization around them. Clear documentation reduces the friction of using systems; clear design documents make decisions reviewable and remembered; clear incident reports turn failures into learning; clear commit messages make the history usable. The engineer who writes well, and who contributes to a culture of clear writing, reduces the friction that poor communication imposes on everyone, and the cumulative effect of clear technical writing across an organization is substantial.
The fourth change is the judgment about AI’s role in writing. The engineer who understands that writing is thinking uses AI for the writing where thinking does not matter and does the writing where it does, preserving the cognitive work that the design document and the difficult argument require. As AI makes it easy to produce fluent text without thinking, this judgment — knowing which writing to do oneself because the thinking is the point — becomes a distinguishing capability.
Resources
Books and Texts
William Zinsser’s On Writing Well (30th Anniversary Edition, Harper Perennial, 2006) is the classic on clear nonfiction writing, and its principles — clarity, simplicity, brevity, respect for the reader, the relentless cutting of clutter — are the foundation of good technical writing even though the book is not specifically about technical subjects. Its chapter on writing about science and technology is directly applicable, and its general principles apply to everything an engineer writes. It is the single best book on writing clearly for most engineers.
Strunk and White’s The Elements of Style (4th ed., Longman, 1999) is the concise classic on the mechanics of clear English prose. Its prescriptions are sometimes dated and sometimes contested, but its core — omit needless words, use the active voice, be specific — is sound and short enough to internalize. For the mechanics of sentences, it remains useful.
Steven Pinker’s The Sense of Style (Viking, 2014) is the best modern treatment of why good writing is good, grounding the principles of clear writing in how readers process language. For the writer who wants to understand the reasons behind the rules rather than just follow them, it is the most illuminating book on writing, and its treatment of the “curse of knowledge” — the difficulty experts have writing for non-experts because they cannot reconstruct not knowing what they know — is directly relevant to technical writing’s central challenge.
For the design document specifically and engineering writing broadly, the writing guidance embedded in the engineering practices literature (the Google engineering practices documentation, the writing in The Pragmatic Programmer, and various engineering blogs on design documents) is the practical reference, since the design document is a genre specific to software engineering not covered by general writing books.
| Book | Role | Type |
|---|---|---|
| Zinsser, On Writing Well (30th Anniversary) | Clear nonfiction writing; the foundation | Entry |
| Pinker, The Sense of Style | Why good writing works; the curse of knowledge | Depth |
| Strunk & White, The Elements of Style (4th ed.) | Mechanics of clear prose | Reference |
| Williams, Style: Lessons in Clarity and Grace | Sentence-level clarity at depth | Depth |
Courses and Practice Projects
The Google Technical Writing courses (free, two courses) are also the best structured practice: they include exercises that build the specific skills of technical documentation, and they are short enough to complete and apply quickly.
Writing is learned by writing, with feedback, and revising. The most effective practice is to write the genres you need to produce — design documents, documentation, explanations — and to seek feedback from readers on whether the writing served its purpose. Writing in public (a technical blog, documentation for an open-source project, answers on technical forums) provides both the practice and the feedback, since public writing gets read and responded to. The discipline of revising — writing a first draft, then cutting it down and clarifying it — is where most of the improvement happens, and the writer who revises (rather than treating the first draft as finished) improves both the document and their writing skill.
A specific high-value practice: write the design document before building something significant, and notice what the writing reveals about the design. The experience of discovering, in the writing, a flaw that the writing exposed is the most direct demonstration of writing as a thinking tool, and it builds the habit of using writing to think.
| Resource | Platform | Type |
|---|---|---|
| Google Technical Writing courses (free) | developers.google.com/tech-writing | Practice |
| Diataxis documentation framework (free) | diataxis.fr | Reference |
| Write the Docs guide (free) | writethedocs.org | Auxiliary |
| Microsoft Writing Style Guide (free) | learn.microsoft.com | Reference |
| Writing in public (blog, docs, forums) | Various | Practice |
| Design documents before building | Local practice | Practice |
| Revising drafts for concision and clarity | Local practice | Practice |
Traps
| Trap | Why it misleads | Better response |
|---|---|---|
| Undervaluing writing as not “real” engineering | Engineers who entered the field to work with machines often regard writing as a peripheral skill, secondary to the technical work, and neglect it. This is a structural mistake: influence scales with communication, and beyond a certain seniority, writing is the primary medium of impact. The engineer who cannot write is limited to the influence of what they can build alone, regardless of the quality of their ideas. | Treat writing as a core engineering skill and invest in it deliberately. The return is high and compounds with seniority. The engineers whose ideas shape what their organizations build are the ones who can write those ideas clearly; writing is not peripheral to engineering influence but central to it. |
| Writing for oneself rather than the reader | The most common technical writing failure is writing from the author’s position of already understanding, assuming the context the author has and the reader lacks. The result is documentation that makes sense only to someone who already understands the system, design documents that assume knowledge the reviewer does not have, explanations that skip the steps the expert finds obvious. Pinker calls this the curse of knowledge. | Write from the reader’s position of not yet understanding, which the author must deliberately reconstruct because they no longer occupy it. Identify who the reader is and what they know, and provide the context they need. Test writing on an actual representative reader where possible; the points where they get confused reveal the curse-of-knowledge gaps the author cannot see. |
| Burying the point | Writing that builds up to its conclusion, narrative-style, forces the technical reader — who is usually reading to extract a specific point — to read to the end to find it. The reader who wants the recommendation, the result, or the answer should not have to excavate it from the bottom of the document. | Lead with the conclusion. Put the point first — the recommendation, the result, the answer — and then the supporting detail for those who need it. The reader who needs only the point gets it immediately; the reader who needs the justification reads on. This inverts narrative structure and is correct for technical writing. |
| Treating the first draft as finished | First drafts are too long, contain unclear passages, and bury the point — this is true even for skilled writers, because the first draft is where thinking is worked out, not where it is presented well. Submitting the first draft delivers the writer’s working-out rather than a document shaped for the reader. | Revise. Cut the first draft down to the essential, clarify the unclear passages, restructure for the reader, lead with the point. Most of the improvement in writing happens in revision, and the discipline of revising — rather than treating the first draft as done — is what separates effective writing from working-out delivered raw. |
| Outsourcing the writing that is thinking | Using AI to draft the design document for a hard problem, or the argument for a significant decision, skips the thinking that writing it was supposed to force — the discovery of unhandled cases, flawed steps, and gaps in understanding. The AI produces a fluent document that conceals rather than exposes these gaps, and the writer gets a document while losing the thinking that was the valuable part. | Distinguish the writing where thinking matters from the writing where it does not. Use AI for routine documentation, boilerplate, and mechanical drafting, where the friction-reduction is a clean win. For the writing that is thinking — the hard design, the significant argument, the explanation requiring deep understanding — do the writing yourself to force the thinking, using AI to polish rather than to replace the cognitive work. And verify all AI-drafted content, which can be confidently wrong. |
中文
清楚写作，是工程师能够培养的最高杠杆能力之一；而那些进入这个领域是为了与机器打交道、不是为了与文字打交道的人，往往会持续低估它。这种低估是错误的，原因具有结构性：工程师的影响力会随着其沟通能力扩展；到了一定资历之后，写作就是影响力的主要媒介。一个没有被清楚写出的设计，不会被认真考虑。一个没有被清楚论证的提案，不会说服他人。一个没有清楚记录推理过程的决策，会被无休止地重新争论。那些真正塑造组织构建什么的工程师，除极少数例外，都是能够把自己的想法写得足够清楚，使他人能够理解、评估并采纳的人。无法被沟通的技术能力，只能影响持有者自己单独能构建的东西。
写作也是思考工具，而不仅仅是把已经形成的想法传达出去的工具。把某个东西写下来——一个设计、一个论证、一段解释——会强迫产生一种仅凭思考可以逃避的精确性。头脑中似乎清楚的想法，一旦试图被精确写出，就会暴露出缺口、矛盾和模糊之处。这就是为什么写设计文档常常会改变设计：写作本身会暴露那些靠含混带过所遮蔽的问题。写作的工程师不只是记录自己的思考；他们也在改进自己的思考，因为写作正是松散思考被发现并修正的地方。逃避写作的实践者，也逃避了本可以磨利其思考的纪律，而他们的思考会因此变差。
本节讨论工程师会产出的几种技术写作文类——文档、设计文档、提案、提交信息和 pull request 描述、事故报告、解释性写作——以及让技术写作在这些文类中都有效的原则。它是阅读技术文献（§8.7）的输出对应物：让文献值得阅读的同样精确性和结构，也是写作者必须产出的东西。本节还必须处理 AI 写作辅助如何改变这项活动；它确实有用，也确实危险，因为写作就是思考，而外包写作可能意味着外包思考。
前置知识：阅读技术文献（§8.7）——读过好的技术写作，并感受过糟糕技术写作的代价之后，会写得更好。你所写主题的领域知识。一般写作能力；技术写作是在此基础上专门化，而不是替代它。
这项能力的形状：为读者写作，并借此清楚思考
技术写作，是为了特定读者和特定目的，清楚传达技术信息的技艺。它有两个定义性特征：它服务读者；它磨利作者的思考。这两点组织了这项能力的一切。
第一个特征是，技术写作以读者为中心，而且比多数其他写作更是如此。技术文档的读者，是带着任务来读的——理解一个系统、评估一个提案、按照规范实现、修复一个问题。写作成功与否，取决于它是否帮助读者完成这个任务。这是比文学意义上的“好写作”更尖锐的标准：技术写作之所以好，是因为读者读完之后能够做他们来做的事。这个以读者为中心的标准，推出了这门技艺的原则：知道读者是谁、他们需要什么；组织文档，使他们能找到所需内容；按照能够建立理解的顺序表达；保持精确，使他们不被误导；保持简洁，使他们的时间不被浪费。技术写作的每一条原则，都是对服务读者目的的展开。
第二个特征是，写作是一种思考工具。新手想象写作是对已经完全形成的思想的转录：先想清楚，然后写下来。有经验的写作者知道，写作正是思考完成的地方，因为写作所要求的精确性，会暴露思考所容忍的缺口。写设计文档会揭示设计中未处理的情况；写论证会揭示某一步并不成立；写解释会揭示你并没有像自己以为的那样理解某个东西。这不是思考或写作的缺陷；这正是写作改进思考的机制。接受这一点的写作者——为了发现缺口而精确写作，并把发现的缺口看作写作的意义，而不是烦人的障碍——是在用写作更好地思考，而不只是记录思想。
技术写作最好通过文类来理解，因为每一种文类都有自己的目的，而目的决定形式。文档服务于试图使用系统的读者，其形式遵循 §8.7 的分层结构：概览、教程、参考。设计文档服务于正在评估技术决策、以及日后试图理解该决策的读者，其形式呈现问题、拟议方案、考虑过的替代方案和推理过程。提案服务于正在决定是否做某件事的读者，其形式用于提出理由并说服。提交信息和 pull request 描述服务于未来恢复意图的读者（§8.3，§8.5），其形式解释为什么。事故报告服务于组织从失败中学习（§4.10），其形式是不归咎个人地分析发生了什么以及为什么发生。每一种文类的形式，都由其读者的目的决定；知道某种文类，就意味着知道它的读者需要什么。最近与这项能力有关的发展是 AI 写作辅助，下文会处理；它可以起草任何这些文类，因此也诱使写作者跳过这些写作本应产生的思考。
清晰性、结构与技术写作文类
清楚技术写作的原则
清楚的技术写作建立在一小组原则之上，这些原则适用于所有文类，并且都服务于读者提取所需内容的能力。
了解读者，并为他们写。相同内容面对不同读者时，必须以不同方式书写：面向工程团队的设计文档，可以假定某些知识；面向高管的提案则不能。识别了读者的写作者——知道他们知道什么、需要什么、为什么要阅读——能够正确调整写作；没有识别读者的人，则会写出对某些读者过难、对另一些读者过浅的文本，最终两边都无法服务。任何技术文档的第一个问题，都是它写给谁；这个答案会塑造其他一切。
先给结论。技术读者通常是为了提取特定信息而阅读，不是为了被带入一段旅程；他们不应该读到最后才找到重点。服务他们的结构，应当把结论放在前面——建议、结果、答案——然后为需要的人提供支撑细节。这与其他写作中常见的叙事结构相反，后者通常铺垫到结论；而技术写作中采用结论先行是正确的，因为读者想先得到答案，然后在需要时再看理由。论文摘要、设计文档摘要、良好技术邮件中的结论先行结构，都是为了服务需要快速获得重点的读者。
为导航而组织结构。技术文档是被导航的，而不是被线性阅读的：读者会扫描自己需要的章节，跳到相关部分，然后只仔细阅读与自己有关的内容。服务这种阅读方式的写作，会提供可导航结构：信息量充足的标题、合乎逻辑的组织、帮助读者判断哪些部分需要细读的摘要。一个必须线性阅读才能理解的文档，会辜负那些只需要其中一部分的读者；而多数技术文档的大多数读者，正是这种读者。
要精确，也要简洁；二者相容，并且都服务于读者。精确意味着准确说出什么为真，避免迫使读者猜测含义的模糊性——准确命名事物，准确陈述数量，区分确定事实和推测。简洁意味着用足以服务目的的最少文字表达，不用废话浪费读者时间，也不让内容被埋没。二者结合，会用最少阅读努力传达最多信息，而这正是技术读者需要的效率。多数技术写作都会通过删减变得更好：第一稿通常过长，把它修改到本质——删除重复、铺垫、无必要的限定——会改善文本。
设计文档
设计文档是技术写作最直接塑造工程的文类，写好它是一项独立且有价值的能力。设计文档为一个问题提出技术方案，并给出足够细节和推理，使他人能够评估它；同时也留下足够记录，使未来工程师能够理解系统为什么会变成现在这样。它是重大技术决策被做出并被记住的产物。
有效设计文档的结构，遵循读者的评估路径：问题——我们要解决什么，为什么重要？拟议方案——采用什么方法？考虑过的替代方案——还能怎么做，为什么这个方案更好？取舍和风险——代价是什么，可能出什么问题？以及评估和实现所需的必要细节。替代方案部分，是区分设计文档和宣传材料的关键：公平呈现替代方案，并解释为什么偏好拟议方案，说明这个决策是凭判断做出的，而不是默认选择；它也使审阅者能够评估决策，而不是只能接受决策。只呈现选定方案、没有替代方案的设计文档，不是设计文档，而是辩护书；它剥夺了审阅者评估选择的能力。
在构建之前写设计文档的纪律，是其作为思考工具价值最大的地方。写设计会迫使人在进入代码之前，先考虑各种情况、替代方案、失败模式和取舍；而此时处理它们成本较低。如果一个设计文档在写作过程中揭示出拟议方案存在致命缺陷，那么它已经完成了自己的工作——它在缺陷被构建出来之前捕捉到了缺陷。这就是为什么对重大工作先写设计文档、再审查、最后构建，是一种高杠杆工程实践：它把问题发现前移到成本更低的位置，并产生记录，使日后能够理解这个决策。
较小文类：提交、Pull Request、事故与文档
较小文类比设计文档写得更频繁，而它们对代码库和组织的累积影响很大。提交信息和 pull request 描述（§8.5）服务于未来恢复“为什么做出某项改动”的读者；写得好，它们让历史成为可用记录；写得差，例如只有 “fix”“update”，就浪费了记录推理的唯一机会。纪律是解释为什么——动机和语境，而这些内容代码本身并不包含——表达要简洁，但也要足够完整，使未来读者能够理解。
事故报告（§4.10）服务于组织从失败中学习，其形式是不归咎个人的分析：发生了什么，按什么顺序发生，为什么发生，也就是根因而不是责备，以及将改变什么来防止复发。这里最重要的写作原则是精确——准确说明发生了什么、以什么顺序发生——以及无责框架，即关注系统性原因而非个人过错。正是这种框架，使报告成为学习工具，而不是惩罚工具，也使人们愿意写出诚实的报告。
文档服务于试图使用系统的读者，写好它要遵循分层结构（§8.7）：传达模型的概念概览，让读者开始上手的教程，精确记录细节的参考文档。最常见的文档失败，是只写一层：例如只有参考文档而没有概念概览，于是读者可以找到每个函数，却不理解模型；以及为作者而不是读者写作，即假定作者拥有而读者缺少的语境。好文档是从读者“尚未理解系统”的位置写出来的；而作者已经不再处于这个位置，因此必须有意识地重建它。
AI 写作辅助：起草与思考
AI 写作辅助可以起草任何技术文类——根据描述生成设计文档，根据 diff 写提交信息，从代码生成文档，起草某个概念的解释。对于写作中的机械部分，这确实有用：它消除产生第一稿的摩擦，提供措辞建议，起草没人想写的常规文档，并帮助第一语言不是文档语言的写作者写出流畅文字。用于这些目的时，它是真实的生产力辅助。
危险则很具体，并且来自“写作是思考工具”这一事实。如果写设计文档的价值，很大程度上在于写作所强迫的思考——发现未处理的情况、有缺陷的步骤、理解中的缺口——那么让 AI 来写设计文档，就跳过了本来最重要的思考。AI 会生成一份流畅文档，但它可能遮蔽而不是暴露那些你自己写作时本会发现的缺口，因为 AI 并不拥有你对问题的具体理解，也不能完成本该完成的思考。把设计文档外包给 AI 的写作者，得到了一份文档，却失去了思考；这笔交易比表面上更糟，因为思考才是有价值的部分。
有效关系，是区分哪些写作中思考很重要，哪些写作中思考不重要。对于常规文档、样板文本和机械性起草，AI 辅助是明确收益——其中思考较少，减少摩擦是真实收益。对于写作即思考的文本——困难问题的设计文档、重大决策的论证、要求深入理解的解释——写作者应当亲自完成思考，这意味着要亲自完成足够多的写作来强迫思考；AI 可以用于润色和辅助，而不是替代认知工作。在所有情况下，写作者仍然对内容负责：AI 起草的技术写作可能自信地错误，可能陈述不真实的内容，因此必须由理解材料的写作者验证。AI 时代的能力，是知道哪些写作可以委托、哪些必须自己做，并在重要之处维持“以写作促思考”的实践，哪怕 AI 让跳过它变得很容易。
熟练之后会发生什么变化
清楚写作的能力，会改变工程师的影响力，也会改变其思考质量。
第一种变化，是影响力能够扩展到自己单独能构建的东西之外。能够清楚写作的工程师，可以提出被采纳的设计，做出有说服力的论证，记录能够留存的决策——他们的想法塑造组织构建什么，而不仅仅是塑造他们自己构建什么。随着资历上升，工作从亲自构建转向指导他人时，这种以写作为媒介的影响力会成为主要影响形式；能够写作的工程师拥有它，而不能写作的工程师，无论想法质量多高，都被限制在个人贡献范围内。
第二种变化，是由于精确写作的纪律，思考会变得更锋利。写下设计、论证和解释的工程师，会让自己的思考接受写作所要求的精确性，并捕捉单凭思考会容忍的缺口和错误。他们的思考因为被写过而变得更好；用写作来思考的习惯——用设计文档找出设计缺陷，用书面论证检验逻辑——是一种思考纪律，会提升技术判断质量。
第三种变化，是周围组织会变得更有效，也更人性化。清楚文档减少使用系统时的摩擦；清楚设计文档使决策能够被审查并被记住；清楚事故报告把失败转化为学习；清楚提交信息让历史可用。写得好的工程师，以及推动清楚写作文化的工程师，会减少糟糕沟通施加在每个人身上的摩擦。整个组织中清楚技术写作的累积效果，是相当可观的。
第四种变化，是对 AI 在写作中角色形成判断。理解写作就是思考的工程师，会把 AI 用于那些思考不重要的写作，并亲自完成那些思考很重要的写作，从而保留设计文档和困难论证所需要的认知工作。当 AI 让不经思考也能产生流畅文本变得容易时，这种判断——知道哪些写作必须自己做，因为思考才是重点——就成为一种区分性能力。
资源
书籍与文本
William Zinsser 的 On Writing Well（30 周年纪念版，Harper Perennial，2006）是清楚非虚构写作的经典，其原则——清晰、简单、简洁、尊重读者、持续删除杂乱内容——虽然不是专门关于技术主题，但正是良好技术写作的基础。它关于科学与技术写作的章节可以直接应用；其一般原则也适用于工程师所写的一切内容。对于大多数工程师来说，这是关于清楚写作的最佳单本书。
Strunk 和 White 的 The Elements of Style（第 4 版，Longman，1999）是关于清楚英语散文机制的简洁经典。它的一些规定有时过时，也有争议；但其核心——删掉不必要的词、使用主动语态、保持具体——是可靠的，而且短到可以被内化。对于句子机制，它仍然有用。
Steven Pinker 的 The Sense of Style（Viking，2014）是关于为什么好写作之所以好的最佳现代处理，它把清楚写作原则建立在读者如何处理语言的基础上。对于想理解规则背后原因，而不是只想遵守规则的写作者，这是最有启发性的写作书。它对“知识诅咒”的处理——专家很难为非专家写作，因为他们无法重建自己不知道当前知识时的状态——与技术写作的核心挑战直接相关。
至于设计文档和更广义的工程写作，工程实践文献中嵌入的写作指南，例如 Google engineering practices documentation、《The Pragmatic Programmer》中的写作，以及各种关于设计文档的工程博客，是实践参考。因为设计文档是软件工程特有文类，通常不会被一般写作书覆盖。
| 书籍 | 作用 | 类型 |
|---|---|---|
| Zinsser，On Writing Well（30 周年纪念版） | 清楚非虚构写作；基础 | 入门 |
| Pinker，The Sense of Style | 好写作为什么有效；知识诅咒 | 深入 |
| Strunk & White，The Elements of Style（第 4 版） | 清楚散文的机制 | 参考 |
| Williams，Style: Lessons in Clarity and Grace | 句子层面清晰性的深入处理 | 深入 |
课程与实践项目
Google Technical Writing courses（免费，两门课）也是最好的结构化实践：它们包含训练技术文档具体能力的练习，而且篇幅短，能够较快完成并应用。
写作要通过写作、反馈和修改来学习。最有效的实践，是写你需要产出的文类——设计文档、文档、解释——并向读者寻求反馈，了解这份写作是否完成了目的。公开写作，例如技术博客、开源项目文档、技术论坛回答，同时提供练习和反馈，因为公开写作会被阅读和回应。修改的纪律——先写第一稿，再删减并澄清它——是大多数进步发生的地方。会修改的写作者，而不是把第一稿当成完成稿的写作者，会同时改善文档和写作能力。
一个高价值的具体实践是：在构建某个重要东西之前，先写设计文档，并注意写作揭示了设计中的什么问题。在写作过程中发现一个由写作暴露出来的缺陷，是写作作为思考工具最直接的证明，也会建立用写作思考的习惯。
| 资源 | 平台 | 类型 |
|---|---|---|
| Google Technical Writing courses（免费） | developers.google.com/tech-writing | 实践 |
| Diataxis documentation framework（免费） | diataxis.fr | 参考 |
| Write the Docs guide（免费） | writethedocs.org | 辅助 |
| Microsoft Writing Style Guide（免费） | learn.microsoft.com | 参考 |
| 公开写作（博客、文档、论坛） | 多种平台 | 实践 |
| 构建之前写设计文档 | 本地实践 | 实践 |
| 为简洁和清晰修改草稿 | 本地实践 | 实践 |
陷阱
| 陷阱 | 为什么会误导 | 更好的回应 |
|---|---|---|
| 低估写作，认为它不是“真正的”工程 | 许多进入工程领域是为了与机器打交道的人，会把写作视为边缘能力，认为它次于技术工作，并因此忽视它。这是一个结构性错误：影响力会随沟通能力扩展；到了一定资历之后，写作就是影响力的主要媒介。不会写作的工程师，无论想法多好，其影响都会被限制在自己单独能构建的东西上。 | 把写作当作核心工程能力，并刻意投入。它的回报很高，而且会随着资历增长而复利增加。真正塑造组织构建什么的工程师，是能够把想法清楚写出来的人；写作不是工程影响力的外围，而是其中心。 |
| 为自己写，而不是为读者写 | 最常见的技术写作失败，是从作者已经理解的立场出发来写，假定读者拥有作者拥有、但实际上缺少的语境。结果是：文档只有已经理解系统的人才看得懂；设计文档假定审阅者并不知道的知识；解释跳过专家觉得显然的步骤。Pinker 称之为知识诅咒。 | 从读者尚未理解的位置写作；作者必须刻意重建这个位置，因为自己已经不在其中。识别读者是谁、他们知道什么，并提供他们需要的语境。条件允许时，把文本交给有代表性的真实读者测试；他们困惑的地方，就是作者看不见的知识诅咒缺口。 |
| 把重点埋起来 | 像叙事一样逐步铺垫到结论的写作，会迫使技术读者——他们通常只是来提取一个具体重点——读到最后才找到它。想要建议、结果或答案的读者，不应该需要从文档底部把它挖出来。 | 先给结论。把重点放在前面——建议、结果、答案——然后为需要的人提供支撑细节。只需要重点的读者可以立刻获得；需要理由的读者可以继续读。这反转了叙事结构，但对技术写作来说是正确结构。 |
| 把第一稿当成完成稿 | 第一稿通常过长，包含不清楚的段落，也会埋没重点——即使熟练写作者也是如此，因为第一稿是思考展开的地方，不是良好呈现的地方。提交第一稿，就是把写作者的思考过程原样交给读者，而不是交付一份为读者塑形过的文档。 | 修改。把第一稿删减到本质，澄清不清楚的段落，按照读者需要重新组织，并先给重点。写作的大部分改善都发生在修改中；修改的纪律，而不是把第一稿视为完成稿，区分了有效写作和未经处理就交付的思考过程。 |
| 外包那些本身就是思考的写作 | 用 AI 起草困难问题的设计文档，或重大决策的论证，会跳过写作本应强迫产生的思考——发现未处理的情况、有缺陷的步骤、理解中的缺口。AI 会生成流畅文档，但它遮蔽而不是暴露这些缺口；写作者得到文档，却失去了真正有价值的思考。 | 区分哪些写作中思考重要，哪些写作中思考不重要。用 AI 处理常规文档、样板文本和机械性起草，在这些地方减少摩擦是明确收益。对于写作即思考的任务——困难设计、重大论证、需要深度理解的解释——要亲自写，借此强迫思考；AI 可以用于润色，而不是替代认知工作。并且要验证所有 AI 起草内容，因为它可能自信地错误。 |