技术写作与文档2022news.ycombinator.com
Ask HN：有哪些值得读的技术写作好书？
Ask HN: Any great books about technical writing?
导读
这是一则 HN 求助帖：发帖人想找能帮初级开发者乃至资深工程师提升技术写作的书，覆盖 issue 描述、公告、文档、用户手册等场景。评论区给出两条互补路径：一是读经典写作书、练习通用文风；二是用结构化写作方法（如金字塔原理）组织技术内容。对需要写文档、写方案、写公告的写作者，这是一份实用的入门书单与自查清单。
可以直接用的写作要点
- 01
别只在“技术写作”类书里找答案，先把 Zinsser、Stephen King、Bradbury 这类经典写作书读透，文风问题多半是通用问题。
- 02
把奥威尔六条当成交稿前的自查清单：删掉陈词滥调的比喻、能用短词就不用长词、能删的字就删、能用主动就不用被动、能用日常词就不用行话术语。
- 03
写之前先搭结构：结论先行、分层支撑（金字塔原理），让读者一眼看到主张，再决定要不要往下读细节。
- 04
用“读者的大脑如何理解”来解释写作规则（如 Pinker），比死记硬背规则更容易迁移到新场景。
HN 评论精选
写技术文档要先学好通用写作，并用奥威尔式规则和公司风格指南做约束。
我觉得技术写作类的书都很干巴无聊。真正帮我提升技术写作的，是 Bradbury、Stephen King、Pressfield、Zinsser 这些经典写作书。另外可以遵循奥威尔的那几条原则：不要用你在印刷品里见惯了的比喻；能用短词就别用长词；能删的字一定删掉；能用主动语态就别用被动；能用日常英语表达，就别用外来语、科学术语或行话；但在说出粗劣句子之前，宁可先破这些规则。大厂的开发者文档风格指南（如微软、谷歌的 style guide）里也常能捡到好东西。
thenerdhead查看英文原文
I think all technical writing books are dry and boring. The best books I've read that helped me with technical writing have been classic writing ones such as Ray Bradbury, Stephen King, Steven Pressfield, William Zinsser, and more. Also following this general guideline from Orwell may help: i. Never use a metaphor, simile or other figure of speech which you are used to seeing in print. ii. Never use a long word where a short one will do. iii. If it is possible to cut a word out, always cut it out. iv. Never use the passive where you can use the active. v. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent. vi. Break any of these rules sooner than say anything outright barbarous. https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/ You may also find some gems here and there with big tech companies developer documentation contribution style guides i.e. https://docs.microsoft.com/en-us/style-guide/welcome/ https://developers.google.com/style
从认知原理理解写作规则，比死记硬性规则更有效。
我喜欢 Pinker 的《风格感觉》(A Sense of Style) 的思路：他的写作建议建立在人的心智如何运作之上。与其给你一堆僵硬规则，不如让你从认知理论层面理解为什么要这样写。
neves查看英文原文
I liked the approach of Pinker's book "A Sense of Style": https://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century He gives writing tips based in how the mind works. Instead of a bunch of rigid rules, you can understand it based in cognitive theory.
用金字塔原理先搭结构：结论先行、分层论证，是技术写作的骨架。
你要找的应该是《金字塔原理》(Minto Pyramid Principle)，一本讲如何组织结构的不朽之作。理解之后，你会发现它在现实中到处被应用；同时你也会开始讨厌那些没有这样结构的写作，因为读起来不必要地啰嗦、也更难理解。这本书在亚马逊内部被大量使用和推荐，而亚马逊正以书面叙述的文化著称。
Denzel查看英文原文
The Minto Pyramid Principle is what you're looking for - https://www.amazon.com/NEW-Pyramid-Principle-Writing-Thinking/dp/B09W2VPVJX/ref=tmm_pap_swatch_0?_encoding=UTF8&qid=&sr=. A timeless book on how to structure writing. Once you understand it, you'll start to notice applications of the book out in the wild. You'll also start to loathe writing that isn't structured as such because it's needlessly tedious and more difficult to understand. The Minto Pyramid Principle is heavily used and recommended within Amazon, a company famous for their culture of written narratives.
网上零散技巧很多，但系统的技术写作书单反而稀缺。
我是一名职业技术写作者。刚入行时我拼命找技巧和窍门。网上（当时和现在）满是零散技巧，但我找不到一份技术写作的书目。我很快会发布一份技术写作书籍与指南的书目，完成后我会在这里贴链接。
pivic查看英文原文
I am a professional technical writer. When I started out, I desperately looked for tips and tricks. Internet was (and is) full of tips but I could not find a tech-writing bibliography. I will soon publish a bibliography of books and guides regarding technical writing. I promise to paste a link here when I am finished, which I believe I will be in a day or two.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选