技术写作与文档2019news.ycombinator.com
Show HN：我写了一本关于 GNU grep 与 ripgrep 的书
Show HN: I wrote a book on GNU grep and ripgrep
导读
这是一位作者为自己自出版的技术书《GNU grep 与 ripgrep》做的推广：限时免费下载，配套代码、示例文件和样章都放在 GitHub，PDF 由 pandoc+xelatex 生成。评论区并没有讨论内容本身，而是集中批评这本书的文字质量（冠词大量缺失、像是翻译中丢了东西），对任何打算收费或发布的写作者都是很直接的提醒。
可以直接用的写作要点
- 01
面向初学者又要能当参考书，就得从零讲清基础概念，同时提供大量可直接上手的例子，让读者能边查边用。
- 02
付费或正式发布前一定要请人（或至少自己通读一遍）校对：缺冠词这类小错累积起来，会让读者觉得“内容再好也不值这个钱”。
- 03
把示例文件、代码片段和样章放到公开仓库，既能降低读者的试读门槛，也能自然换来具体的反馈。
- 04
写作时优先追求可读性而非炫技：功能再强、性能再高，如果读者读不懂，传播效果就会大打折扣。
HN 评论精选
文字硬伤会直接摧毁付费产品的可信度。
这本书应该先过一遍编辑。全文到处都缺冠词（a、an、the），明显是翻译或生成过程中丢了东西。发在博客或 HN 评论里无所谓，但如果你要收钱，那就是另一回事了。
iamnotacrook查看英文原文
This should be run past an editor. The text is missing articles (a, an, the) all over. Something obviously got lost in translation. It's fine for a blog or comment on HN or whatever but if you're asking for money...
好内容也需要专业编辑打磨，别把内容好当作不编辑的借口。
拜托拜托，请个编辑吧。你的内容很好，只是需要编辑加工。
rmbryan查看英文原文
Please please please hire an editor. You have good content that needs editing.
性能和可读性常常此消彼长，写作同样要在“高效”和“易懂”之间做取舍。
当休闲读物看挺有意思：拿任意一个 BSD 工具和 GNU 版本的源码对比一下。BSD 的 tail 通常短小漂亮，GNU 的则要复杂一些。GNU 工具可能性能很高，但往往很难读懂。
etaioinshrdlu查看英文原文
For fun casual reading, try comparing the source code of any BSD utility vs. GNU. BSD tail: https://searchcode.com/codesearch/view/457515/ GNU tail: https://github.com/coreutils/coreutils/blob/master/src/tail.c Usually the BSD one is short and sweet and the GNU one is a bit complex. GNU utilities may be high performance but they tend to be hard to understand.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选