技术写作与文档2022thenewstack.io编辑精选
工程师教你写出开发者喜爱的文档
An engineer’s tips for writing documentation devs love
导读
这是一篇面向工程师的文档写作经验总结，核心观点是：好文档不是把知识倒出来，而是站在读者角度降低理解成本。对写作者来说，它把"为读者写作"落到了可操作的方法上，包括用新手测试文档、区分教程与参考手册、把清晰表达当作专业形象的一部分。
可以直接用的写作要点
- 01
别对读者说"这很简单"。读者卡住时，第一反应应是检查文档哪里没讲清楚，而不是怪读者水平不够。
- 02
把教程/示例和参考手册分开写：示例负责帮人快速上手，参数、类型、取值、含义的清单负责帮人查具体信息，两者不能互相替代。
- 03
找一个没用过这份文档的新手，让他在你不出声帮助的情况下边操作边说出想法，你会立刻发现大量歧义和坑。
- 04
把文档当成对外展示专业度的窗口：能把复杂系统讲清楚，本身就会让读者相信你和你的团队真的懂。
- 05
介绍任何工具或 DSL 时，先讲清它要解决什么问题、需要读者额外学什么，而不是强调它"简单"。
HN 评论精选
别用"这很简单"打发读者；强调简单只会让学不会的人感到挫败。
"你会惊讶有多少人被劝退：别人告诉他们某个东西很简单，可对他们来说并不简单。"这句话应该成为每个平台/基础设施工程师的座右铭。别告诉我你的 DSL 很简单，别告诉我 Puppet 很简单因为"它用的就是 Ruby"，也别告诉我 HCL、Terraform 或者那些 YAML 很简单因为"它们就是 YAML"。它们并不简单。别逼我学这些东西。不是我不愿学，而是我想学的是基础知识，而不是你那套不可迁移、半年就过时的东西。
hintymad查看英文原文
> "You'd be surprised how many people get turned off by seeing something that other people tell them is simple, and then it's not simple to them." This. This should be every platform/infrastructure engineer's motto. Don't tell me your DSL is simple. Don't tell me that Puppet is so simple because oh my god, it uses Ruby. Don't tell me that HCL or terraform or whatever yaml crap is so simple because "they are in yaml". No. They are not. Don't. Make. Me. Learn. It's not because I don't want to learn. It's because I want to learn fundamentals instead of your specific, non-generalizable, 6-month-or-less half-life stuff.
清晰的文档是最好的专业形象广告，值得投入专业编辑。
我很喜欢（DigitalOcean）"把文档当营销"这个思路。每次读到他们的文章，我都会想：哇，他们的工程师一定很懂行，才能把事情解释得这么清楚。我之前不知道他们有一支专业编辑团队，致敬！另一个文档写得极好的团队是 Cloudflare 写复盘/事故报告的团队，他们能把复杂系统的级联故障讲得非常清楚。我希望更多开发者/工程师能这样写东西。
solardev查看英文原文
I love this idea (for digitalocean) of "documentation as marketing". Every time I read one of their articles, I feel like "oh wow their engineers must really know what they're doing, to be able to explain this so clearly". I didn't know they had a team of professional editors... kudos! Another team that's really great at producing documentation is the Cloudflare retrospectives/postmortems folks, who can very clearly explain the cascading failures from complex systems. I wish more devs/engineers wrote like that!
用新手做可用性测试，是发现文档问题最快的方法。
一个极其有效的技巧：看着一个初级开发者使用你的文档，不要提供任何帮助，让他边想边把思路和操作说出来。你会发现几十处歧义、"坑"和不足！每次都要用新的初级开发者（用过你文档的人不能再用）。而且要让他完成一个真实任务（不是校对文档，而是真的按文档用途去用它）。我用过 Salesforce 和 Google 的文档，能看出来他们从没这样测试过，因为里面有些明显的问题，几分钟就能发现并修好。我经常用这个方法，收获巨大。
nomilk查看英文原文
Insanely effective tip: watch a junior dev use your docs, offer no assistance, and have them say out loud what they're thinking and doing. You'll discover dozens of ambiguities, 'gotchas', and shortcomings! It's important to use a new junior each time (i.e. if they've used your docs before, don't use that person again). They should also try to accomplish a real task (not just proofreading the docs, but actually using the docs for their intended purpose). I've used docs from Salesforce and Google and can tell they haven't been tested in this way since they contain (glaring) problems that would easily be found and addressed in a few minutes. I use this approach often, and gain enormously from it.
示例不能代替参考手册；读者需要能直接查的参数清单。
我讨厌那种只给示例和教程的文档趋势。示例适合入门，但除此之外基本没用。请直接给我一份参数/属性清单，写明含义、类型和可能取值。比如 Kubernetes 的文档对我来说是噩梦，因为它不是真正的文档，只是一堆示例。不仅查具体信息效率极低，而且如果我这个用例恰好不在示例里（大多数时候都不在），我就可能到处翻几个小时，最后才发现有个 x.y[0].z 键正好能实现我要的功能。另一个例子是 GitHub Actions：你得翻很久才可能找到接近 YAML 规范的东西，而且藏得很深、很混乱，搞不清哪个属性属于哪一层。相比之下 CircleCI 就非常容易。
Seb-C查看英文原文
I hate the trend of documenting by giving only examples and tutorials. Examples are nice to get started, but completely useless otherwise. Please just give me a list of possible parameters/properties with their meaning, type and possible values. For example, the Kubernetes documentation is a nightmare to me because it's not a real documentation, just a bunch of examples. Not only it is very inefficient to look for a very specific piece of information in that, but if my case happens not to be in it (which is most of the time) I can waste hours looking everywhere to finally learn that there is actually a x.y[0].z key that does exactly what I need. Other example: Github actions. If you look hard enough, you may find something close to a yaml specification, but it's quite hidden, confusing and difficult to understand which property belongs to what. In contrast, CircleCI is extremely easy.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选