技术写作与文档2021andregarzia.com编辑精选
写一本技术书
Writing a Technical Book
导读
这是一篇关于如何写技术书的实战经验总结：作者强调先做大纲、把「写初稿」和「编辑修改」当作两个阶段，并比较了自出版与传统出版的利弊与工具选择。对任何想写书或写长文的写作者来说，它提供了一套从结构规划到修订流程的可操作思路。
可以直接用的写作要点
- 01
动笔前先写详细大纲，把章节结构和读者路径定下来，后面写起来会省力得多。
- 02
把写作拆成两个阶段：初稿阶段只求把想法倒出来，真正的重头戏是之后的编辑与修订。
- 03
选一套能减少格式负担的工具链（如 Markdown + Pandoc 一次性输出多种电子书格式），把精力留给内容。
- 04
出版不只是写完书，营销是同样难甚至更难的一半，动笔前就要想好读者在哪里。
HN 评论精选
认同「大纲先行、编辑最难」，并用亲身经历记录传统出版的漫长流程。
我很喜欢这篇文章，尤其是关于大纲的部分，想写作的人应该认真对待。作者说写作是容易的部分、编辑才是难的部分，我完全同意。我把自己为 Manning 写书和改稿的近两年经历写成了日记，记录传统出版的流程和写技术书这场漫长苦役的感受。
rickumali查看英文原文
I liked the information in Andre's post. Aspiring writers would do well to heed his thoughts on outlining. He also states that writing is the easy part and editing is the hard part, and I completely agree. I wrote a diary during the almost two years I spent writing and revising a book for Manning Publications. I muse about the trad pub process and my feelings on the great slog that is writing a technical book. http://www.gitmol.com/blog/
自出版胜在自由、传统出版胜在专业编辑；有人觉得初稿比修订更难。
自出版最大的好处是完全掌控流程：不受出版社对章节结构、插图、习题等的规范限制，可以送免费副本、放免费网页版、公开源码，甚至边写边按章发布。但传统出版最让我怀念的是专业编辑看稿，以及电子书的排版和封面质量。「编辑修订让初稿变得可交付」这件事我反而喜欢，像捉虫，改掉一个就爽一次；对我来说更难的是写初稿，因为要先花时间梳理思路、查资料、做研究。
asicsp查看英文原文
>Self-publishing ... PRO: You have full control over all the process really. This is one of the best things I like about self publishing. I am not restricted by guidelines set by a publisher regarding chapter structure, images, exercises, etc. I can give away free copies, put up free web versions, share source code, etc. And recently I've tried sharing content chapter wise as I write the books. >Traditional publishing ... PRO: You have professional editors looking over your draft. I miss this aspect of traditional publishing the most. Also applies to quality of the ebook (formatting, cover, etc) produced. >The hard part is editing and revising it so that your draft becomes something that is good enough to share. I actually like the editing and revising part. It's somewhat like bug hunting and feels good to squash them. Creating the first draft has been more difficult for me, since it takes time to organize my thoughts about what I should put in, reading documents, researching ideas etc. When I'm editing, most things are already in place and easier to keep myself occupied with smaller list of tasks.
营销才是自出版最难的一环，曝光不等于销量。
好文！我学到了一些以前不知道的工具，会去试 Reedsy 和 Scrivener，我用过 Leanpub，它几乎帮我把一切都做好了。对我来说最难的是营销。庆幸的是我最初是为自己写这本书，把它写完本身就当成一种成就。我跟很多人聊过，他们以为写书很容易发财，我并不这么看。推广时也很难不显得用力过猛；技术书除了 Reddit 社区和 Twitter，我根本不知道从哪儿开始。我甚至被邀请去线上会议分享，听众看起来是真感兴趣，结果销量是零 :)
flaie查看英文原文
Good reading! I did learn a lot regarding tools I didn't knew and I will definitely check Reedsy and Scrivener, I did use leanpub which was really good, doing almost everything for me. The hardest part is about marketing for me, and I am happy that I first wrote the book for me and see the completion as an achievement, I talked with a lot of people who thought it was kind of easy to get rich just writing books, I don't think so, not easily. Also, it's really tough to promote a book without feeling like you're over-trying to do it, and regarding an IT book, except for a reddit community, or twitter I wouldn't know where to start. I have even been invited to online conferences, people seemed to be interested (don't think they were faking it), but it generated zero sales :)
用 Markdown + Pandoc 一套源文件输出多种格式，减少排版返工。
感谢这篇好文。我一辈子只写过一本技术书，发现 Pandoc 必不可少。比如写一本关于 Vim 的书时，我只用 Markdown 写，Pandoc 就能把它转成各种电子书格式。Pandoc 开箱即支持语法高亮，可惜当时没有 VimL 的，我只好自己实现，但 Pandoc 允许我扩展。我很好奇 Scrivener 能不能做到这些，它支持语法高亮吗？
yanis_t查看英文原文
Thanks for a fantastic post. I've actually wrote a single tech book in my life, and found Pandoc to be really indispensable. For example, while writing a book about Vim* I simply used markdown and Pandoc would allow me to translate it to all the different e book formats. Pandoc supports syntax highlighting out of the box. Unfortunately, there wasn't one for VimL, so I had to implement it myself, but Pandcon would allow me to extend it. I wonder if that's possible with Scrivener? Does it even support syntax highlighting? * https://www.vimfromscratch.com/book
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选