技术写作与文档2019performancejs.com编辑精选
撰写技术书籍的建议
Tips for Writing a Technical Book
导读
这篇帖子分享写技术书的实用建议，HN 评论补充了写书的现实：它更像热情项目，收入低且营销自负；同时也给出把博客文章改成章节、用工具管理主题、建立内容管线等方法。对写作者来说，这些经验既能调整预期，也能直接改进写作流程。
可以直接用的写作要点
- 01
把写书当成热情项目而非致富途径，提前接受收入低、营销自负的现实。
- 02
卡在“必须完美”时，先写博客文章，再改造成书稿章节；每章也应尽量能独立阅读。
- 03
用 Trello、OneNote 等外部工具管理全书主题，不要试图把整本书同时装进脑子里。
- 04
建立选题管线：持续收集素材、提炼核心概念并归入相应章节，让书稿内容保持新鲜。
HN 评论精选
提供写技术书的延伸资源和 HN 搜索线索。
谢谢，这非常及时：我最近也收到一位约稿编辑的冷邮件，正在研究写技术书这个有趣的话题。:) 我找到一些有用资源：Scott Meyers 给潜在作者的建议、Tryggvi Björgvinsson 的《I wrote a book》、Ian Miell 的《Writing a technical book》，以及 HN 上的相关讨论，可以搜索“ask hn + writing a book”。
nbaksalyar查看英文原文
Thank you, this is very timely: recently I got a cold email from an acquisition editor too and been researching this fascinating topic of writing tech books. :) Some more helpful resources I found: - Advice to Prospective Book Authors from Scott Meyers (of Effective C++ fame): https://www.aristeia.com/authorAdvice.html - "I wrote a book" by Tryggvi Björgvinsson: https://dev.to/trickvi/i-wrote-a-book-lfg - "Writing a technical book" by Ian Miell: https://zwischenzugs.com/2016/05/15/writing-a-technical-book/ - Then there are some good discussion about this topic on HN. You can try searching by keywords like "ask hn + writing a book", e.g.: https://news.ycombinator.com/item?id=14300932
写技术书经济回报低，作者需自担营销，应视为热情项目。
我做过几本编程书的技术编辑。普通开发者可能没意识到，对作者来说写书是热情项目。你不仅不会发财，能拿到最低工资就算非常幸运了。大部分甚至全部营销都落在你肩上。尽管这是靠畅销驱动的生意，出版商倒是过得不错。
rmason查看英文原文
I've been a technical editor on a few programming titles. I don't think the average developer realizes that for the authors writing a book is a passion project. Not only won't you get rich, you will be extremely lucky to make minimum wage. Most if not all the marketing is on your shoulders. Even though it's a hits driven business the publishers do all right though.
用博客文章作为写书跳板，并接受收入低、错误难免、主动沟通等现实。
如果你能写博客文章，但写书时觉得东西必须完美而卡住，那就从博客文章开始。问问出版商能否发表它们；不行就当作博客来写。然后把博客文章改造成书本章节。博客文章通常更自包含，但书本章节即使能独立阅读也会更受欢迎。其他建议：别指望发财，写作通常比编程赚得少；无论改多少遍，总会发现拼写和语法错误，即使专业文字编辑审过，尽量修正但也接受这一点；做好插图很花时间；除非和出版商谈好，插图会黑白印刷、灰色层次会被毁掉；出版商会给你配项目经理，主动保持沟通，早说延迟会更宽容；维护贡献者名单，有人帮忙就立刻记下姓名和邮箱，半年后你会忘掉一些贡献者。
perlgeek查看英文原文
Another one: If you are fine writing blog posts, but have trouble writing for a book because you think suddenly things need to be perfect (and run into writer's blog)... Then start with blog posts. Ask your publishers if you can publish them. If not, write them as if you'd publish them on your blog. Then take the blog posts, and turn them into chapters of your book. A blog post tends to be a bit more self-contained than a book chapter, but even for a book chapter, people appreciate it if they can read it separately. Other things: * don't expect to get rich. Writing usually pays way less than programming. * no many how many passes you have made, you'll always find spelling and grammar errors (even after a professional copy editor went over it). Try to get them fixed, but also accept it as a fact of life that things won't end. * Making good illustrations takes quite some time. * Expect illustrations to be printed black and white, with grays being butchered, unless you have negotiated otherwise your publisher. * The publisher has a project manager for you. Keep them updated. They'll be more lenient with delays if you tell them early. Communicate as much as you'd do with a project manager at your job, even if they don't ask you every week or month (because they don't want to be pushy). * Keep a list of contributors, where you add names and email addresses as soon as somebody helped you. After half a year, you would forget at least a few contributors. List people by name in a "Thank you" section. Everybody likes to read their own name in a book :-) * Keep a list of people + email addresses who expressed interest in your project. The publisher likely will send out ebook copies to people, in the hope that they will review your book on amazon. Be prepared for that.
用外部工具管理全书结构，并建立持续提炼素材的选题管线。
很棒的文章！我想补充：人几乎不可能同时把整本书的内容装进脑子里。我非常依赖 Trello 和 OneNote 来整理主题。写作过程中建立主题管线也很关键。作者总会遇到想收入书中的新文章或博客，高效地把原始内容提炼成核心概念并写入书稿章节，对保持内容新鲜和相关很重要。
mfrisbie查看英文原文
Fantastic article! I would add that it is quite impossible to hold the contents of an entire book in your head at once. I rely heavily on Trello and OneNote for mental organization of topics. It's also critical to form a topic pipeline as you go about writing. Unfailingly, writers will come across articles or blog posts that contain something new they'd like to include in their text. Efficiently taking raw content, boiling it down into its essence, and composing that concept into a book section is important for keeping your book content fresh and relevant.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选