技术写作与文档2012johndcook.com编辑精选
为什么要读技术书、写技术书？
Why read and write tech books?
导读
这篇讨论技术书为何值得读、为何值得写：作者式叙事能带来比零散资料更深的理解，但技术书的篇幅、结构与质量常受市场和技术更新影响。对写作者而言，它提醒我们思考如何用连贯叙事组织模块化内容，并兼顾当代读者的跳读习惯。
可以直接用的写作要点
- 01
用一条作者主导的叙事线串起各章节，让读者不是只收集零散知识点，而是形成整体理解。
- 02
把长书设计成若干约30页的短文或章节，每篇可独立阅读，又共同服务一个总叙事。
- 03
篇幅应服务于“用最少页数讲清最多内容”，不要为了显得厚或符合印刷习惯而注水。
- 04
在连贯叙事之外保留清晰的跳读入口，适应读者不愿从头读到尾的习惯。
HN 评论精选
技术书篇幅常受印刷与市场影响；可用“系列短文+总叙事”组织，并探索更简洁的严肃写作形式。
关于“由具体作者写出的叙事能带来更深理解”这一点很好，但叙事多长才合适？技术书的长度是由印刷技术和市场压力决定的（人们觉得书厚才值回票价），而不是由“用最少页数传授最多理解”决定的。技术书通常分成每章约30页，这也接近多数独立技术文章的长度。因此一本书可以被看作一系列较短文章，即使出自同一作者，也构成一个总叙事。我想知道能否比30页文章更简洁，同时仍保持好读、易学、并通过跨多章的叙事带来更深理解。与印刷写作惯例相比，我们仍不擅长用合适的超文本进行长期有用的严肃写作。
rsaarelm查看英文原文
The point about a specifically authored narrative leading to a deeper understanding is a good one, but what about the suitable length for that narrative? The length of technical books is dictated by printing technology and market pressure (people think they get their money's worth if the book looks thick), not by what's the least amount of pages that can impart the most understanding. Technical books are generally divided into chapters somewhere around 30 pages in length. This is also in the ballpark of the length of most standalone technical articles. So the book can be thought of as a series of shorter articles that form an overarching narrative, even if it's by a single author. I wonder if things can go even more concise from the 30 page article form, and still maintain the property of being pleasant to read, easy to learn from and imparting a deeper understanding through a narrative going through multiple chapters. We are still bad at using proper hypertext for long-lasting useful and serious writing compared to the conventions in writing for print.
技术书整体质量参差、佳作稀少；免费在线先行也说明篇幅未必由印刷和市场决定。
Petzold 完全正确（他的《Programming Windows》仍是极好的资源）。只是并非所有技术书都达到他设的高标准。多数技术书只是“又一本技术书”，但偶尔会出现《Learn You a Haskell》或《Eloquent JavaScript》这样的作品。各类书都如此：少数珍宝藏在垃圾堆里。（另外回应 rsaarelm：我提到的两本书在有人考虑出版之前很久就可免费在线阅读；它们的长度绝非由印刷技术或市场压力决定。）
FreakLegion查看英文原文
Petzold is absolutely right (and his Programming Windows is still a fantastic resource). It's just that not all technical books live up to the high bar he's set for them. Most technical books are JATBs ("Just Another Technical Book"), but every once in a while we get a Learn You a Haskell or Eloquent JavaScript. It's the same with every kind of book: a few gems hidden in a mound of trash. (Also re: rsaarelm's comment, the two books I mention above were available for free online long before anyone gave a thought to publishing them. Their length is in no way dictated by printing technology or market pressure.)
技术更新带来持续市场，写技术书可建立权威并提升个人价值。
一个有点功利的角度：新技术总在出现。技术从业者觉得必须跟上最新技术才能保持价值。因此还算过得去的技术书在持续更新的市场里卖得像糖果。你也能借此把自己确立为最新技术的权威，提高自身被感知的价值。
glimcat查看英文原文
A somewhat mercenary perspective: There is always new tech coming out. Tech workers have a perception that they must be up on the newest tech in order to remain valuable. Halfway decent tech books therefore sell like candy in a continuously renewed market. You also establish yourself as an authority on the newest tech, increasing your own perceived value.
现代读者习惯跳读，技术书应兼顾叙事连贯与可跳读性。
买了消费者预览版，喜欢这种写作风格。如今技术写作者的挑战是读者变得没耐心，他们没法坐着等你讲完整个故事，而是直接跳读。所以书最好既有叙事性，又便于跳读。
chj查看英文原文
Bought the consumer preview edition. Love the writing style. The challenge nowadays for tech writers is people become impatient, they can't sit there and wait for you to tell the whole story. They simply jump. So it would be better that the book is narrative and also jump-friendly.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选