技术写作与文档2022news.ycombinator.com编辑精选
Ask HN：优秀技术写作有哪些例子？
Ask HN: Examples of good technical writing?
导读
这是 HN 上一则征集「优秀技术写作范例」的讨论帖，回帖推荐的作品横跨科普、数学教材、内核文档和漫画博客，评判标准不是技术难度，而是「整体感觉」：语气、呈现方式、可读性。对写作者来说，这是一份难得的『他人如何做到清晰』的清单：有的靠诗意，有的靠毫无跳跃的推演，有的靠人格化的表达，值得对照自己的写作检查。
可以直接用的写作要点
- 01
把「清晰」当成最高标准：好的技术文本应该提供一条从「不懂」到「懂」最直接的路，读者卡住时随时能回到你这里。
- 02
叙述要连贯，不留下逻辑跳跃：每一步都交代清楚前因后果，连孩子都能跟上；这往往意味着作者要先想清楚。
- 03
同一主题可以用完全不同的语气完成：既能写得像诗，也能写得像说明书，先想清楚你想要哪一种阅读体验。
- 04
用稳定的系列长文拆解复杂主题：分篇、互相链接、保持统一风格，让读者可以按自己的节奏深入。
HN 评论精选
最优秀的写作可以兼具诗意与清晰，而清晰本身就是一种可追求到极致的品质。
James Gleick 的《Chaos》（混沌理论史）和《The Information》（信息论史）写得极其优美、富有匠心，你会忘了它们是技术书——科学史写作所能达到的、最接近诗的程度。另一本枯燥得多、但清晰度满分的是 Axler 的《Linear Algebra Done Right》，它陪我读完了数学本科和博士；课上或别的教材里有看不懂的地方，我总能回到 Axler，找到从无知到理解最直接的那条路。
wkschwartz查看英文原文
James Gleick‘s “Chaos”[0] (history of chaos theory) and “The Information”[1] (history of information theory) are so beautifully and artfully written you might forget they’re technical. As close as (history of) science writing comes to poetry. A lot drier but top marks for clarity: “Linear Algebra Done Right” by Axler.[2] It got me through both undergraduate and PhD math degrees. When something was confusing in a lecture or another textbook, I could always return to Axler for the most direct path from ignorance to understanding. [0]: https://www.amazon.com/Chaos-Making-Science-James-Gleick/dp/0143113453 [1]: https://www.amazon.com/Information-History-Theory-Flood/dp/1400096235 [2]: https://linear.axler.net/
持续、成系列、风格统一的深度写作，是技术媒体的核心竞争力。
LWN.net 上几乎任何文章都值得读——他们的长篇专题、技术会议报道等等。我马上想到的是 2013 年那组共 7 篇的 Linux 内核 namespaces 系列，第一篇底部有全系列链接。他们的内核文章档案和按年份整理的会议报道也都很出色，比如最近的 Linux 存储、文件系统、内存管理与 BPF 峰会综述。
kashyapc查看英文原文
Almost anything written by the inimitable LWN.net[1] — their feature-length articles, technical conference coverage, etc. Something that springs immediately to mind is their 7-part series[2] Linux kernel namespaces from 2013. The full series is linked to at the bottom of part 1: - Namespaces in operation, part 1: namespaces overview — https://lwn.net/Articles/531114/ (2013) You can see their entire kernel archives here[3]. And as to their excellent conference coverage, you can browse conferences by year[4]. Most recently, here's[5] their roundup of "Linux Storage, Filesystem, Memory-Management and BPF summit". [1] https://lwn.net [2] https://lwn.net/Articles/531114/#series_index [3] https://lwn.net/Kernel/ [4] https://lwn.net/Archives/ConferenceByYear/ [5] https://lwn.net/Articles/lsfmm2022/
好的讲解每一步都没有逻辑跳跃；好的写作还会纠正读者习以为常的错误前提。
Charles Petzold 的《Code》非常出色：它清清楚楚地带着读者走过构成今天复杂计算机系统的各个部件和步骤，每一步都解释得没有逻辑跳跃，小孩子都能跟上。George Box 的《Improving almost anything》让我大开眼界——我们从小被教导实验必须一次只改一个因素，这是错的；这样做反而错过了因素之间的交互效应（想想烹饪里的温度和时间）。书里讲了很多如今看来老旧、但很基础的方法，用很少的数据就能大幅改进模型。
ImageXav查看英文原文
Code: The Hidden Language of Computer Hardware and Software by Charles Petzold is an excellent work that very clearly guides the reader through the components and steps that lead to the sophisticated computer systems we have nowadays. Each step is explained with no logical leaps and could be followed by a young child. Improving almost anything by George Box blew my mind. As children and even as university students we have been lied to. We have been told that experiments must be carried out one at a time to assign effects. This is patently false. In fact, we miss out on potential interaction effects (think temperature and time in cooking) by using one factor at a time experimentation. In this book he discusses many now old but fundamental techniques by which large improvements in models can be gained with minimal data. It has helped me in my career immensely and made me aware of many usual methods and fields of study.
可亲的语气和鲜明的个人风格，能大大降低技术内容的门槛。
Julia Evans 的漫画、小册子和博客文章都非常精彩：易懂、有教学性，而且充满个性。https://jvns.ca/
maxique查看英文原文
Julia Evans' comics, zines and blog posts are absolutely brilliant. Accessible, educational and full of personality. https://jvns.ca/
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选