技术写作与文档2020sararobinson.dev编辑精选
写一本技术书：从构思到付印
Writing a technical book: from idea to print
导读
这是一篇技术书作者复盘从选题到成书的完整流程：提案怎么写、和编辑怎么配合、为什么建议先写代码再写章节。评论区几位同样在写技术书的作者补上了出版业的真实一面——营销基本靠自己、版税很少、句子要反复重写。对想写书或写长系列教程的人，这篇文章能帮你判断该找传统出版社还是自出版，也提醒你预留远比想象中更多的时间。
可以直接用的写作要点
- 01
先把代码和示例写完，再动笔写讲解章节，能避免边写边改、反复返工。
- 02
按“每句话平均要重写三遍”来估算工作量，别用初稿速度预估交稿日期。
- 03
写书提案的重点不是内容多好，而是向出版社证明你有渠道和可信度自己把书卖出去。
- 04
选与你写作类型匹配的出版方，否则编辑会不断把你“塑形”成他们熟悉的好卖模板，最后写的不再是你想写的书。
HN 评论精选
传统出版社主要给你渠道和背书，营销和收入基本得靠自己。
我刚在 Wiley 出过一本技术书，几点体会：别指望出版社帮你营销，好的非虚构提案大部分篇幅其实是在告诉出版社你打算怎么靠自己的资源和信誉卖书，一切都靠你自己。也别为钱写，你只能拿到很小一块蛋糕的 10-15%，想做赚钱的副业又有粉丝基础就自出版。选传统出版社的理由是：他们的书店、图书馆渠道能触达更多人；传统出版还带一点社会认可；我那本图文书只有全彩印刷才成立，需要出版社的资源。
forrestbrazeal查看英文原文
Having recently released a "technical" book with a large traditional publisher (Wiley) [0], here are a few of my learnings: - Expect nothing from the publisher in terms of marketing support. In fact, a good nonfiction book proposal is going to spend most of its length explaining to the publisher how you will sell the book for them through your connections and credibility - not the other way around. It's all on you. - Don't do it for the money. You're going to make 10-15% of a pretty small pie. If you want to write info products as a moneymaking side gig and you have any following at all, self publish! So why go with a traditional publisher? I don't feel this is fully articulated in the OP, but here was my reasoning: - The publisher probably will get your book in the hands of a larger absolute number of people, so if you care about maximizing readership and you don't have a stupid-large online following, their network effects through bookstores, library sales, etc will help you sell more copies than you could on your own (though again, you'll see very little of the money!) - There's still some social proof involved with traditional publishing, and it's a nice thing to do once - just so you know in the back of your head that you "can" - In my case, I was producing a highly graphic book that really doesn't work except in print and in full color, and I needed the resources of a traditional publishing house to make it not look terrible. The Wiley experience was overall positive for me and I don't regret it, but if I ever produce a text-based info product in future it's hard to look away from the ROI advantages of self-publishing. [0] https://www.amazon.com/Read-Aloud-Cloud-Innocents-Inside/dp/1119677629/
写作时间被严重低估：每句都要重写多遍。
我也在写第一本书，真的很难，疫情期尤其难（我原本的计划是在跨大西洋邮轮上写）。写书你会发现：每一句话在开始校对之前就已经被重写了三遍，再加上查资料、做决定、出版流程，花的时间远比看起来多得多。
petr25102018查看英文原文
I am also now writing my first book (https://efficientdeveloper.com/) and it is really difficult, especially during Covid times (my original idea of writing this book was writing it on a transatlantic cruise... ) What you realise when writing a book is that every sentence gets rewritten 3 times, even before you start caring about proofreading. With all the research and decision making, publishing etc. it takes much more time than it looks.
出版社的品类偏好会塑造甚至扭曲你的书，选错合作方会写不下去。
这篇总结很好，说明当你写的书和出版社已有品类相似时，合作能带来很多支持，后续发行也受益。我也向 O'Reilly 等出版社投过一份和它们常规品类不完全一样的提案，走了同样的流程，一个半月后被拒，理由是与我书竞争的另一本书优先级更高。我把提案原封不动投给另一家，被接受了。但最后没成：那家不出版我这类书，编辑不断把我往他们熟悉、好卖的形态上“塑形”，可那不是我想写的书。
gregdoesit查看英文原文
This is a nice summary, and shows the benefit of working with a publisher, when you are writing a book that is similar to ones they have published already. You get a lot of support, and will definitely benefit distribution-wise later as well. Congratulations to the author - especially on publishing relatively quickly, in 10 months from the idea! And it's very nice to read that all royalties are going to Girls Who Code. I've worked with O'Reilly and a few other publishers on a proposal that was slightly different to what they usually publish. I went through the same submission process, working with an acquisitions editor, similar to how it happened in this case. In my case, O'Reilly rejected the proposal after a month and half. The feedback in my case was that the book competes with another project, which project got priority. Sure enough, I took the proposal without any changes to another publisher, worked with the acquisitions editor there, had the proposal accepted and we went ahead with the writing process with a development editor. In the end, working with the other publisher did not work out for me. They did not publish the type of book I was writing, and the feedback from the editors kept nudging me to "shape" the book into the type of book this publisher knew would sell, and would sell well. Unfortunately, it didn't feel like the type of book I was excited to write. A year and some time later, I'm still writing the book -The Software Engineer's Guidebook[1] - and if all goes according to plan, I'll publish it early next year. What I've learned with working with a book publisher, is just how involved the process is. Now, instead of taking a $5,000 royalty upon completion of the manuscript, I'm budgeting to spend around $5,000 out of pocket on development/copy editing, cover design and production editing. The things that the publisher would have otherwise paid for. It's a bit simpler to hire professionals these days for these areas thanks to sites like Reedsy[2], which I do recommend for fellow authors self-publishing in finding support on various publishing tasks. [1] https://www.engguidebook.com/ [2] https://reedsy.com/
先写代码再写章节，且讲解过程会暴露自己没真懂的地方。
我也在写第一本“书”，用 Ruby 重建 Redis。作者说前几节是边写代码边写章节，后来编辑建议先写代码再写章节——这一点我完全赞同，我最近三章就是这么写的，差别巨大，真希望早点知道。另外写书让我学到很多：好多次我想解释某个东西，才发现自己其实并不懂它怎么运作，于是花上几小时甚至几天去查内部实现。
pjam查看英文原文
This is great and really useful to me! I am also, like others here, in the process of writing my first "book": https://redis.pjam.me/. Mainly inspired by https://shop.jcoglan.com/building-git/, rebuilding Redis, instead of git, in Ruby. > For my first few sections I wrote the code as I wrote the sections, but then Lak made the suggestion that it would probably be easier to write the code first and then write the chapter I can echo this a thousand times, I've written the last three chapters this way and this has made a huge difference, wish I had known that earlier! I will also add that it really made me learn so much because even though I thought I knew quite a bit about Ruby (I knew early on that I didn't know much about Redis). So many times I found myself trying to explain something and realizing that I didn't actually know how it worked and ended up spending hours (days?) researching the inner workings of said thing PS: Using quotes around book mostly because that's the imposter syndrome kicking in, I was calling it "a series of blog post" for a while, to kinda downplay it
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选