技术写作与文档2019queue.acm.org编辑精选
必须做与绝不能做：谈如何写好文档
Must and Must Not: On writing documentation
导读
这是 ACM Queue 上关于如何写好技术文档的一篇文章，核心讨论「must not」这类规范性措辞的歧义问题，以及文档写作的基本原则。对写作者来说，它提醒我们：清晰不是天赋而是可以训练的技能，措辞歧义会造成真实的沟通事故。文末评论补充的修订方法、审阅清单和「用问题搭大纲」的技巧，同样适用于一般写作。
可以直接用的写作要点
- 01
把稿子分几天反复修改：隔半天以上再回头读，昨天觉得清楚的地方今天往往就暴露了歧义，改到只剩表面措辞的微调才算定稿。
- 02
沿用「少即是多」的原则：用短句、短段落和常见词，宁可多分几段，也不要用从同义词词典里翻出来的生僻词。
- 03
把「必须」「不得」「可以不做」这类规范性措辞明确写出定义，避免母语不同的读者把「must not」误解成「不必」。
- 04
先用问题搭大纲（这一章回答什么问题？这一段回答什么问题？），逐条作答，最后再把问题改写成小标题或删掉。
HN 评论精选
文档要隔天反复修改，并明确定义容易误解的规范用语。
写文档的首要原则是：隔几天改很多遍。让头脑至少半天（最好更久）没想过这段内容，再回来重读。昨天读起来毫无歧义的内容，今天看就有歧义了。一直改到改动越来越小、只剩下表面措辞的微调为止。写作的目标是简洁、用简单无歧义的语言，让读者读得快、好消化，这是一项必须学习和反复磨练的技能。另外建议明确写出「must not」这类词的含义，因为读者（尤其是非母语者）常常困惑；这花不了多少篇幅，却能为以后省去大量麻烦。
kstenerud查看英文原文
The primary rule of writing documentation is: Revise it, many times, on separate days. You need to keep coming back to it, reading it with a fresh mind that hasn't thought of what you wrote for at least half a day, preferably longer. What seemed perfectly clear yesterday will come across as ambiguous today. You keep revising until the changes get smaller and start to feel cosmetic. Your job is to write concisely, using simple, unambiguous language that's quick to read and easy to digest. It's a skill that must be learned, practiced, and honed. It's also a good idea to explicitly spell out the meanings of "must not" etc, because people (especially non-native speakers) sometimes get confused. Example: https://github.com/kstenerud/concise-encoding/blob/master/cbe-specification.md#terms It doesn't take up much room, but it saves a whole lot of trouble down the line.
用词求简、先想清楚再动笔，引导读者的顺序是写作的真功夫。
「简明英语清单」也很有用，要点就是「少即是多」：词少比词多好懂，短段落比长段落好懂，熟悉的词比你在同义词词典里查到的词好懂。当然，这些指南只有在你已经清楚自己想表达什么时才有用——这才是写好真正的秘诀。搞清楚从「我对这个主题一无所知」到「我理解这个主题」应该按什么顺序引导读者，这更多是艺术而非科学，需要多年练习。
thomascgalvin查看英文原文
Also helpful is the Checklist for Plain English[1]. The gist is "less is more;" fewer words are easier to understand than many words, short sections are easier to understand than long sections, and familiar words are easier to understand than something you looked up in a thesaurus. Of course, these guides are only helpful if you already understand what you're trying to convey; that's the real secret of writing well. Figuring out the correct sequence to walk a reader from "I don't know anything about this topic" to "I understand this topic" is more art than science, and to do so well takes years of practice. [1]: https://plainlanguage.gov/resources/checklists/checklist/
用「每段回答一个问题」的问题式大纲来组织长文。
计算机科学家 David Parnas 有一个帮助写论文有困难的学生的方法：论文的每一章、每一段都应该回答一个问题。先以问题形式列大纲，例如第一章：这篇论文讲什么？第 1 段：本论文解决什么问题？第 2 段：此前有人做过这个问题的研究吗？第 3 段：前人的工作可以改进吗？第二章：我如何着手这个问题…… 然后作者逐条回答这些问题。最后一步通常是：把问题改写成小标题，或者把问题删掉。
herodotus查看英文原文
The computer scientist David Parnas had a great technique for helping his students who were having trouble writing their theses. His idea was this: every chapter and paragraph in your thesis should answer a question. Start your outline with questions. For example: Chapter 1: What is this thesis about? p1: What is the problem tackled in this thesis? p2: Has there been previous work done on the problem? p3: Can the previous work be improved? Chapter 2: How did I approach the problem? and so on. Then the writer started answering the questions. The final step (usually) is to change the questions into headings or remove them.
「must not」不等于「don't have to」，措辞歧义会造成真实事故。
有件相关的事让两位德国同事惹了不小的麻烦。他们被告知某个改动「must not」进入某个版本，可以等到下一个补丁版本再发。他们把「must not」理解成了「must」的否定，就像德语里那样。这是错的：「you must」和「you have to」意思相同，但「you must not」和「you don't have to」并不相同。他们以为自己被告知的是「不必」，于是觉得可以自由地早点把修复交给客户，结果据说害得另一个客户出了故障，直到误会澄清之前，他们还被指责不服从安排。
not2b查看英文原文
There was an incident related to this that got a couple of German colleagues in big trouble. They were told that a specific change "must not" go into a release, it was OK for it to wait for the next patch release. They heard "must not" as the negative of "must", as it is in German. This is wrong: "you must" and "you have to" are the same, but "you must not" and "you don't have to" are not the same. They thought they were being told "you don't have to" but thought they had the freedom to get the fix to a customer sooner. It seems this caused breakage for a different customer and they were accused of being insubordinate until it was sorted out.
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选