技术写作与文档2010jfm3-repl.blogspot.com编辑精选
别再写垃圾文档了
Stop Writing Bullshit Documentation
导读
这篇文章批评技术写作中大量"废话文档"：只罗列 API 和参数，却不解释读者真正想解决的问题、该怎么上手。评论区进一步指出自动生成的文档只能当参考、不能用来学习，以及缺文档的项目会让使用者被迫从零散博客里拼凑用法。对写作者的价值在于：它逼你思考"什么才算有用的说明"，而不只是把信息倾倒出来。
可以直接用的写作要点
- 01
判断文档是否合格的标准是"读者能否靠它完成任务"，而不是"信息是否齐全"。
- 02
自动从源码提取的 API 文档只能当速查手册，教学式的解释必须由人另写。
- 03
不要发布"TODO"或"本文是草稿"的空页面，占位内容比没有内容更消耗读者信任。
- 04
写文档本身就是最好的学习方式：为不熟悉的项目写一份说明，你会被迫搞懂每个环节。
HN 评论精选
自动生成的文档只能当参考，不能承担教学功能。
另外，别再以为从源码里跑 doxygen 生成的输出就算合格的文档了（换成你所用语言支持的任意"从注释自动抽取文档"工具也一样）。作为参考手册它很棒，但用来学习则惨不忍睹。Ruby 的库，说的就是你们。
jwhite查看英文原文
Also, stop thinking that doxygen output from your source code qualifies as adequate documentation. (Insert whatever comment-embedded-docstring-auto-extraction tool your language supports, if not doxygen.) It's great as a reference, but woeful to learn from. Ruby libraries, I'm looking at you.
占位式的空文档比废话更让读者反感。
最近读了 Linux 内核、OpenEmbedded 和 BitBake 的文档，我对废话已经相当厌倦了——但更厌倦的是在并非 wiki 的网页上看到"TODO"和"本文只是个存根"。
hubb查看英文原文
having recently read the documentation for the linux kernel, open embedded, and bitbake, i'm pretty tired of bullshit -- but even more tired of 'TODO' and 'THIS ARTICLE IS A STUB' appearing in web pages that aren't wikis
主动为项目写文档是参与和学习的最佳方式。
有人可能会说，参与开源项目不该只限于 ./configure; make; make install，然后跑去博客上抱怨。更进一步，积极参与也不意味着"svn commit"是你对项目唯一的动作。各位，不妨为你感兴趣却还没有文档的开源项目发起一个文档项目，在这个过程中你会更深入地了解这个项目。
blantonl查看英文原文
one might argue that the process of participating in open source projects shouldn't be limited to ./configure; make, make install; complain in blog post. Furthermore, one might argue that actively participating in open source projects doesn't mean that "svn commit" is the only action you make towards the project. Folks, consider starting a documentation project for an open source project that doesn't have one, and one for which you are interested in. you might learn more about the project by going through that process.
文档缺失会把读者推给零散博客，逼他们自己逆向拼凑用法。
参见 GStreamer 的任何文档——去年秋天我试图用它做项目时很快就领教了。很多组件基本没有文档，我只能去找一些博客文章，里面有人说"嘿，我用这行命令把视频流到了另一台电脑"，然后自己琢磨在 C 里到底该怎么实例化这些东西、把它们串起来、用那套难用的对象系统等等。
jff查看英文原文
See: any documentation on GStreamer, as I rapidly discovered last fall when I attempted to use it for a project. Many of the components are pretty much undocumented; I was reduced to finding blog posts where some guy says "Hey, I streamed a video to a different computer with this command line", then figuring out how exactly you're supposed to instantiate these things in C, string them all together, use the disgusting object system, etc.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选