技术写作与文档2017thenextweb.com编辑精选
自由软件正在受苦：程序员不会写文档
Free software is suffering because coders don’t know how to write documentation
导读
这篇帖子指出自由/开源软件的一大痛点是程序员不会写文档，导致项目难以为人所用。作者认为值得读的地方在于：它把"写文档"当成一项独立的写作能力来讨论，而评论区进一步指出，问题的根源往往不是"不会写"，而是没人愿意做维护性的工作、也没人为技术写作付费——这对任何写说明性文字的人都是有用的提醒。
可以直接用的写作要点
- 01
文档缺失多半是激励问题而非能力问题：人人都想从零造新东西，没人愿意做维护，写作任务设计时要先解决"谁愿意写"。
- 02
把文档仓库和代码仓库分开管理，能让写文档变成一件独立、低门槛、可被单独认可的工作。
- 03
越是希望获得用户和贡献者的项目，文档往往做得越认真——文档是吸引他人参与的入口，值得优先投入。
- 04
别把"用户说想要更好的文档"当作论据：这类需求永远存在，帕累托最优下人们还是会想要更多，论证要落在具体收益上。
HN 评论精选
文档匮乏是意愿与激励问题，不是技能问题；"用户想要更好文档"这类调查无法作为论据。
"不会写"这个说法有问题。人性的一个缺陷是：人人都想建造，没人想做维护（冯内古特语）。大多数自由软件项目完全由志愿者按自己的兴趣贡献而成。开课教"怎么写"能有多大帮助我表示怀疑，这有点像把马牵上船。另外，用那个调查来证明"应该多写文档"也靠不住：我同意这个结论，原文还有其他论据，但我不认为这个调查能当论据——开发者当然希望自己用的库文档更好；即便在文档投入恰如其分的帕累托最优状态下，他们依然会想要更好的文档。我还想要一匹小马呢。
firethief查看英文原文
"Don't know how"? [A] flaw in human nature is that everybody wants to build and nobody wants to do maintenance (Vonnegut). Most free software projects are entirely built by volunteers contributing what they want to. I don't know how much offering classes on "how" would help; it feels like leading a horse onto a boat. Also, the poll seems a suspect way to support the idea that more documentation is justified; I agree with that idea, and TFA has other arguments supporting the point, but I question the utility of the poll as an argument. Developers would like better documentation of the libraries they are using, but they would. In a Pareto-optimal scenario where exactly the right amount of work was put into documentation, developers would still want better documentation. And I would want a pony.
要改善文档，就得给写文档的人回报与地位，并把文档从代码库中独立出来。
技术写作作为一门职业已经死了。太多公司要求技术写作者懂技术不亚于甚至超过开发者，却给更低的薪水、更少的尊重和零话语权。这种态度也渗透到了开源/自由软件圈。想要更好的文档？想办法补偿那些贡献文档的人，不一定非得是钱。把文档仓库和代码库分开。
epc查看英文原文
Technical writing is dead as a profession. Too many companies expect technical writers to be as savvy, or more, as their developers, but for lower pay, less respect, and zero political power. This attitude bleeds through to open source/free software. You want better documentation? Find a way to compensate people for contributing to it, and that doesn't necessarily mean money. Separate your documentation repository from your code base.
文档问题是普遍现象；越是想要用户和贡献者的项目，越会在文档上投入。
这不只是开源的问题，企业内部的软件也是一个大问题。大多数期待并获得用户或贡献者关注的 OSS 项目，往往在更好的文档上下了更多功夫。
austincheney查看英文原文
This isn't just a problem in open source. It is a huge problem in corporate internal software too. Most OSS projects that expect to receive (and actually get) the attention of users or contributors tend to work harder on better documentation.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选