技术写作与文档2009jacobian.org编辑精选
如何写出好文档（第一部分）
Writing good documentation (part 1)
导读
这是一篇关于如何写好项目文档的文章（第一部分），核心主张是：手写、人工组织的文档无可替代，工具只能辅助。HN 上的讨论集中在自动生成文档的局限上，对写作者最有价值的部分是——文档要有优先级和分组、要随代码维护、要与测试文化并重，以及具体的措辞修改示范。
可以直接用的写作要点
- 01
别指望工具替你写作：自动生成只能充当代码的高层索引，真正有用的文档仍需人工编写、组织与编辑。
- 02
给内容分主次：像人类作者那样标注“重要”的模块，别让十几个无关紧要的工具函数淹没真正关键的那一个。
- 03
把相关信息聚在一起：读者会同时关心的函数与类型应当列在一处，而不是按字母或结构散落各处。
- 04
措辞要果断：删掉“pretty”这类削弱语气的词，把“should show”改成“shows”，把“most of the different areas”改成“the most important areas”。
HN 评论精选
自动文档应做高层索引和优先级标注，而不是替代注释；工具缺的正是人类作者的分寸感。
这类工具的主要价值在于呈现代码的高层概览，并支持向下钻取到当前任务相关的部分，而不是替代你去读代码里的注释。很多自动文档工具最糟糕的地方，是反而把本来可以用纯文本写清楚的注释弄得面目全非（Javadoc 凭什么要求我在每段之间写 <p> 才能正确排版？）。如果要提升自动生成文档的可扫读性，我最想要的是一个“重要”标记，可以打在关键的类型、函数上；现有工具完全没有作者那样的优先级意识，把实现核心算法的顶层函数和十几个琐碎的工具函数一视同仁，结果就是一堆无关细节盖住了少数几个真正的要点。另一个我希望能支持的是更好的信息分组：如果一批函数和类型天然会被同时关注，就应该列在一起或彼此关联，可惜大多数自动文档工具都做得很差。
Silhouette查看英文原文
It's interesting that everyone commenting so far has picked up on the auto-documentation issue. The main value of these tools, IMHO, is in their ability to present a high-level overview of the code and support drilling down to find the relevant parts for the task at hand, not as a substitute for just reading comments in the code once you've found it. In fact, one of the worst aspects of many auto-documentation tools is the way they obfuscate comments that would otherwise have been written in plain text. Seriously, Javadoc, why do I have to write a <p> between each paragraph just so you can lay the comments out properly in HTML? To improve the scannability of auto-generated documentation, top of my wish list would be an "important" flag you could put on the key types, functions, etc. Existing tools typically have no sense of priority in the way that a human writer would, giving equal weight to the top-level function that implements an important algorithm and each of a dozen trivial utility functions. Then you wind up with dozens of mostly irrelevant details obscuring the few key points of interest. The other thing I really wish they'd support is much better grouping of related information. If a bunch of functions and types would naturally be of interest at the same time, then they should be listed together or otherwise associated in the documentation. Most auto-documentation tools suck at this, and even those that provide some facilities to do it tend to fall into the obfuscation trap I mentioned earlier.
为满足流程而生的自动文档没人真正阅读，验证存在不等于被人使用。
“自动生成的文档几乎毫无价值”这一点很重要。我参与的一个项目要求文档必须自动生成并挂在构建服务器的某个 URL 上，但根本没人读：开发者读的是代码里的注释，而负责核对清单的人只确认那个页面存在而已。
gr366查看英文原文
I think the point about auto-generated documentation being near worthless is an important one. A project I'm working on has a requirement that the documentation be auto-generated and available at a URL on the build server, but nobody reads it. The developers read the comments in the code itself, and the checklist people just check to see that it's there.
问题不在工具而在文化：注释与代码同处便于同步，缺的是写文档的动力与氛围。
“手写、组织并编辑过的文档无可替代”这句话，放在 rdoc 和 javadoc 身上，指的是那些写在代码旁边的注释。如果你认定自动文档只是类名和方法名的罗列，那它确实很弱；但把文档放在代码旁边本身有真实价值，比如更容易保持同步。问题在于，不管是行内注释还是独立文件，总得有人有动力去写。这让我怀疑作者对这些工具到底有多熟悉——比如他链接的是 rdoc 的 sourceforge 页面，说明他不知道 rdoc 早已并入 Ruby 标准库多年，甚至可能根本没用过。真正的关键问题是文化，不是工具。有些 Ruby 开发者津津乐道于 Ruby 出色的测试文化，我倒希望听到同样热情的文档文化；因为工具都齐了，却依然不够。
jamesbritt查看英文原文
"There’s no substitute for documentation written, organized, and edited by hand." Which, in the case of rdoc and javadoc, are the docs written as comments with the code. If you assume auto-generated docs are nothing but class and method names, then yes they are weak. But there is real value in having the docs right there with the code; much easier to keep in sync, for example. The thing is, whether inline or in separate files, someone has to feel motivated to write them. It makes me wonder just how familiar the author is with these particular tools. Linking to an rdoc sourceforge page, for example, tells me the author does not know that rdoc has been part of Ruby's stdlib for a few years now, and may never have even used it. The big issue here is culture, not tools. Some number of Rubyists boasts of Ruby's eminent testing culture. I wish I would hear the same enthusiasm for a robust documenting culture as well; because all the needed tools exist but aren't sufficient.
逐句示范如何删冗余、改语气：去掉弱化词，用肯定的动词，把“大部分”换成“最重要的”。
在“教程 > 展示项目‘手感’”那一条下，原句是“This means you that it should be pretty cross-sectional…”，我认为应改成“This means, for your purposes, that it should be pretty cross-sectional…”。此外我还会直接删掉“pretty”，把“should show”改成“shows”，并把“most of the different areas”换成“the most important areas”。写文章要果断有力！
onewland查看英文原文
Under Tutorials > Demonstrate how your project “feels.” bullet, the second sentence is: This means you that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project. I think it should be: This means, for your purposes, that it should be pretty cross-sectional; a good tutorial should show off most of the different areas of the project. I'd also just strike out the "pretty" there and replace "should show" with "shows". Maybe replace "most of the different areas" with "the most important areas". Be forceful in your writing!
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选