技术写作与文档2012floopsy.com编辑精选
WTFM——把手册他妈的好好写出来
WTFM - Write The Freaking Manual
导读
这篇短文呼吁开发者像写代码一样认真写文档——不是只给几个入门示例，而是一份完整的参考手册。对写作者来说，它讲的其实是同一个道理：读者的困惑不会因为作者的省略而消失，把默认值、边界情况、异常说明白，才是对读者真正的尊重。
可以直接用的写作要点
- 01
写说明性文字时，别只给“快速上手”的示例，要把规则、默认值、边界情况和会出错的地方逐条列清。
- 02
假设读者一无所知：作者眼中“显而易见”的内容，对读者往往正是缺口。
- 03
文本优于视频：可检索、可跳读、可反复查证的形式，比让人从头看到尾的形式更耐用。
- 04
文档写完只是开始，过期内容比没有内容更糟——写作要预留维护的成本。
HN 评论精选
读者要的是完整、精确的参考手册，而不是零散示例；文档缺失是态度问题，不是时间问题。
我恨不得给它投一百万票。我就是那种在使用一门语言或库之前，想把整本参考手册从头读到尾的人：它到底做什么、正确的用法是什么、不做什么，我都要先弄清楚。这样既能做出知情的选择，长期也省下大量时间。但现在流行“先发出去再说”，好文档好像不再酷了，就像语法里的花括号一样。好文档的例子：PHP、jQuery、MySQL；糟糕的例子：Python、CoffeeScript（最差）。1.0 之前版本变化快，文档不全还能理解，但一个东西存在一年以上还这样就说不过去了。我不要那种堆一堆例子的“入门指南”，也不想靠在控制台里敲命令去猜对象有哪些方法。我要的是一本像样的参考手册：语法规则、空白符的精确规则、运算顺序、所有函数与参数、回调收到的参数（这个最常被漏掉）、默认值、标志位取值、所有可能的返回值、会抛出的具体异常，以及哪些入参会导致未定义行为。
crazygringo查看英文原文
I would upvote this a million times if I could. I'm one of the kinds of people who wants to read the entire reference manual, front to back, before using a programming language, library, etc. I want to make sure I know exactly what it does, the proper way to use it, and what it doesn't do. This is both so I can make an informed choice about the technology, and it saves a huge amount of time in the long run. But it seems like there's a big trend now to just "get things out there" and that good documentation isn't "cool" anymore, kind of like braces in syntax. Examples of good docs: PHP, jQuery, MySQL. (The first two sites include user comments too, which make things even more useful.) Examples of terrible docs: Python, CoffeeScript (the worst) I can at least understand insufficient docs for pre-1.0 versions when the implementation is changing constantly, but when something has been around for more than a year, it's just inexcusable. I don't want a "getting started" guide that gives a bunch of examples. I don't want to type in the console to find out what methods an object has. I want a friggin' reference manual, that includes (as applicable) syntax rules, exact rules governing whitespace, orders of operations, all functions, all parameters, parameters passed to a callback (why are these forgotten so often?), default values, flag values, all possible return values, specific exceptions that can be thrown, what input parameters result in undefined behavior. Really, it's just not that hard. It may be grunt work, but if you'd rather make your users waste a cumulative 25,000+ hours figuring things out, rather than you spending 100 hours of your own explaining things, I just can't have respect for your product, no matter how otherwise amazing it is.
文档的成本和收益不对称：写的人不爱写、维护更难，过期文档比没有更糟，所以很多人宁可让读者读源码。
做开源时（我大多是一个人做，时间有限又没有报酬），我得选：写代码还是写文档。前者我很享受，后者我一点也不喜欢，你猜我选哪个。少数几次真写了文档，我觉得根本没人看过。而且写完只是开头，还得维护；过期的文档也许比没有文档更糟。我自己也不读文档，因为它们常常过期，只有正式规范是例外。做开源时我干脆读源码，源码永不过期，而且讲的是完整的故事。文档作者觉得显而易见的东西，我未必觉得；反之亦然。第一个跑来跟我要文档的人，就顺便来写吧，愿不愿意都得写。
exDM69查看英文原文
When it comes to open source work, which I mostly do on my own, limited time and don't get paid for, I have a choice. I can spend time writing code or writing documentation. The former I enjoy very much, the latter I don't like at all. Guess which I am going to pick. The times when I've actually ended up writing some docs, I don't think anyone has ever read them. And writing the docs is just the beginning, they have to be maintained too. Out of date docs are perhaps worse than no docs at all. I don't read docs either, because they tend to be out of date. Formal specifications are an exception. But when it comes to open source, I just tend to read the source because it's never out of date and tells the whole story. What was obvious to writer of the doc isn't obvious to me and vice versa. The first person who comes to me asking for documentation to my projects volunteers to write them, like it or not.
文档应以文字为主：可搜索、可索引，视频只适合当教程。
还有，光有“看视频版”是不够的。我没时间为了搞清几个配置项，去看或在一段四十分钟的视频里翻来翻去。文档这件事上文字为王。视频适合做教程，但我需要的是一份索引清晰、可以搜索的扎实参考资料。
jackalope查看英文原文
And please, WTFV isn't enough. I don't have time to watch or search through a 40 minute video to find out how to set a few configuration options. Text is king when it comes to documentation. Videos are fine for tutorial purposes, but I need a solid reference that's well indexed and searchable.
“够用”的文档最稀缺；与其抱怨不如动手贡献，文档可用性直接决定项目能否获得用户。
其实很多开源项目文档很好，也有很多完全没有文档；真正稀缺的是“仅仅够用”的文档。许多项目也允许你参与写文档，所以与其批评自己在用的项目，不如去帮忙维护，哪怕只是提 bug 报告。如果你的项目用户很少，常常就是因为别人搞不懂怎么用就走了。想要名气（也许还有钱）？先把项目做到能用。
smoyer查看英文原文
There are actually many open-source projects that have excellent documentation and there are many that don't have documentation at all. I think there's actually a shortage of projects with simply adequate documentation. Many open-source projects also allow you to contribute to the documentation, so I don't think you should criticize projects you're actually using but rather that you should help maintain the documentation (even if it's just bug reports). If you have an open-source project with very few users, you'll often find that you can't get traction simply because when people can't figure out how to use your software, they'll go elsewhere. Want fame and (maybe) fortune? Make your project useable.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选