技术写作与文档2010jacobian.org编辑精选
如何写出优秀的文档
Writing great documentation
导读
这是 Jacob Kaplan-Moss 关于如何写好技术文档的经典文章在 HN 上的讨论。评论者围绕写作态度、教程的"诚实度"以及文档缺失的代价展开，观点对任何写说明性文字的人都有用。技术写作和一般写作的底层要求其实是同一件事：想清楚，才写得清。
可以直接用的写作要点
- 01
语法混乱、表达别扭，往往是理解不到位的信号——写不顺的时候，先回头确认自己到底懂没懂。
- 02
好文档需要时间，不要指望一次成型；把"先写出来再反复修改"当成固定工序。
- 03
不必等成为专家才动笔，专业深度不是写好文档的前提；写作本身就是检验理解、暴露盲点的过程。
- 04
教程别做得太"顺滑"，以至于掩盖了真实的使用门槛——要让读者在真实难度下成功走完一遍。
HN 评论精选
写不清楚往往是想不清楚；好文档要花时间，专家身份不是前提，知识应该用来扶人而不是压人。
有四条规则应该纹在每个技术写作者的手背上，好让他们不会不小心忘掉：1. 语法糟糕、文笔差，往往说明理解也不到位。2. 好文档需要花时间。3. 深厚的专业能力并不是写好文档的天然前提。4. 别让那种过度推崇"什么都知道"的工作文化占据上风——"掌握内情"应该是帮别人上来的工具，而不是用来压人的棍子。
p3ll0n查看英文原文
Four rules that should be tattooed on the back of every technical writer’s hands so they can’t accidentally forget it. 1. Poor grammar and bad writing are often a sign of poor comprehension. 2. Good documentation takes time. 3. Deep expertise is not automatically a prerequisite for good documentation. 4. Don’t let working cultures that put too great a premium on knowing everything dominate - i.e. being 'in the know' should be a tool for helping others up rather than beating them down.
教程要诚实地呈现真实难度，过度简化反而误导读者。
我真希望能给这条点十次赞。我很喜欢那个观点：别把教程做得太简单，以至于它无法代表真正使用这项技术所需的水平。
frossie查看英文原文
I wish I could upvote this ten times. I loved the comment about not making your tutorial so easy that it becomes unrepresentative of the level required to use the technology.
没有文档的代码等于失败；检验标准是别人用它是否比他自己重写更省力。
就我个人而言，我宁愿某人干脆别写这个开源项目，也不愿他写了却不写文档。理解别人的思路本来就难，没有文档更是难上一个数量级。如果普通 hacker 觉得"自己重写一个实现"比用你的库还容易，那你就失败了。
tsally查看英文原文
Personally I'd rather someone not write an opensource project than write it and not document it. Understanding someone else's thought process is hard and it gets to be an order of magnitude more difficult without documentation. If it's easier for your average hacker to write his/her own implementation than use your library, you've failed.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选