技术写作与文档2021jmtirado.net
2021年如何写一本编程书
Writing a Programming Book in 2021
导读
一位作者回顾自己 2021 年写编程书的经历：从博客起步、选题定位、自出版与找出版社的取舍。它值得写作者读，是因为文中既有作者自己的做法，也有评论区对技术书行业的尖锐反思：许多编程书更像是作者资历的“证明”，并非为读者服务。
可以直接用的写作要点
- 01
先靠持续写博客验证自己的内容是否有吸引力，再用数据（访问量、停留时长）确认自己确实能写出让人读得下去的东西，然后再动笔写书。
- 02
切入一个足够窄的细分需求，别写面面俱到的大部头：读者没耐心看完，差异化才是卖点。
- 03
技术写作面向实用读者，句子要短、用词要简单，目标是让读者快速获取信息，不必追求文学性。
- 04
把代码片段放进代码仓库统一管理，方便随版本更新；动笔前先想清楚读者为什么该买你这本，而不是市面上已有的上千本同类书。
HN 评论精选
先用博客数据验证写作能力，选细分领域、写简单直白的句子，并优先考虑自出版。
我最近写了几本书，给想写书的人几条建议：先写博客，努力做到日均几千次浏览、平均停留超过 5 分钟，用客观数据证明你能写出有吸引力的内容；找一个细分领域，我的书只讲如何用 Scala API 快速上手 Spark，其他书讲理论、同时讲四种语言 API、或者按字母顺序罗列 DataFrame 方法，大多数人没耐心读大部头；把阅读难度控制在中学水平，短句、简单词，技术读者只要信息，不在乎文笔；把代码片段放进仓库，方便更新。有出版社找过我，但我选择自出版，因为这种技术主题出版社给不了多少有价值的反馈，而且出版社只给 20% 版税，自出版能留下 80% 以上——除非出版社能提供额外价值，否则不必合作。
MrPowers查看英文原文
I wrote a couple of books recently and have some tips for aspiring authors: * Start by blogging. Try to get thousands of daily pageviews with an average time on page > 5 minutes. Objectively verify you're able to write content that's engaging. * Try to fill a niche. My book is focused on practical advice for getting productive with Spark using the Scala API quickly. There are other books that cover theory, discuss all 4 language APIs simultaneously, and are API documentation narratives (e.g. Chapter 4 will cover all the DataFrame methods in alphabetical order). Most people don't have the attention span for huge books. * Target middle school reading level. Short sentences & simple words. Technical audiences want information and don't care much about literary prose. * Organize your code snippets in a repo, so it's easy to update your book I got some offers from publishers, but went the self-publishing route cause I didn't think that a publisher could give too much valuable feedback on such a technical topic. Lots of my blog readers told me my blogs are easy to follow, so I felt confident I didn't need a professional editor. Publishers pay 20% royalties and self publishing lets you keep 80%+, so you should only go with a publisher if they can add that extra value. Writing a book was a great experience for me. It's an easy way to train folks who are new to Spark. Several folks have emailed me, told me they can't afford the book, and I've sent them free copies. Don't think writing books is a great way to make money, but it's great if you have altruistic motives.
技术书常是作者资历的背书而非服务读者，别把“出过书”当成专业水平的证明。
关于“可信度”那一点很有意思：一个人写过技术书，光因为写书本身很难，就自动显得很厉害，人们也容易假定他懂很多。很多年前我给一家出版社做代码类图书的技术审校，很明显有些作者其实并不真懂自己在写什么——他们知道的刚好够写出一本书，但错误很多。我认为很多技术书是用来“证明”作者可信、懂行的，而不是为读者服务或赚钱：技术作者知道自己赚不了多少，写书更多是为了虚荣心和职业前景，作者并不需要真的写对。尤其是《X 入门指南》《24 小时学会 X》这类书：有经验的开发者不会去读它挑错，新手买了也看不出写得差，所以作者写一堆垃圾照样能自称专家。因此我已经不再因为简历上写着“出过书”就特别佩服一个人了。
onion2k查看英文原文
The point about Credibility is interesting. There's something about someone who's written a technical book that automatically seems impressive just because writing a book is hard, and it's easy to assume that the person knows a lot. A long time ago I used to do technical review for a publisher on books about code. It was pretty obvious that some authors didn't really know what they were talking about. They knew enough to write something, but there were always a lot of mistakes. I think many technical books are written to act as a 'proof' that the author is credible and knows their topic well rather than as an exercise in serving the reader or an attempt to make money. Tech authors know that they've not going to make much. It's more an exercise in vanity and improving job prospects. The author doesn't really need to be right. Especially "Beginner's guide to X" or "Learn X in 24 hours" books, experienced and knowledgable developers won't be reading the book to criticise it, and new developers who buy it won't know it's poorly written, so an author can write any old junk and still claim to be an expert. Consequently I've stopped being particularly impressed by people who have authored books on their resume.
编程书的体裁陈规可以打破：写薄一点，去掉教材噪音，照顾注意力不集中的读者。
编程书这个体裁需要被重新定义。我大学时选修一门“一学期学完一年内容”的现代分析课，三周后就要交作业，我几乎没开始，差点被数学专业开除（当时我正忙着用 Fortran 打孔卡做国际经济学模拟，搞得一塌糊涂）。我一直庆幸《Baby Rudin》是那么薄的一本书。辅修英语让我明白：体裁不是必然的，而是文化的选择。我越来越能坦然承认自己属于神经多样性（你可以代入任何 ADHD 缩写），我最好的学生里也有很多这样的人；意识到这点让我成为更好的老师。比如数学符号不过是别人写得很糟的代码，读不懂别怪自己。我几乎讨厌自己读过的每一本编程书，总怕翻到下一页就要跟着写一个音乐播放器。REPL 示例永远保留所有面向初学者的“鸟道”提示，而有审美的人第一周就会把 REPL 调成隐藏噪音、给输出上色。当我处于 ADHD 的迷雾中时，几乎找不到书页上的代码示例。
Syzygies查看英文原文
The programming book genre needs to be redefined. In college I was nearly thrown out of my math major, after giving no evidence of having started a year-in-a-semester modern analysis course, with three weeks to go. (I had been busy with a disastrous International Economics computer simulation using Fortran punched cards. Why, when Dukakis ran for president, did no one ask if "the world blew up his year?") I am forever grateful that "Baby Rudin" is such a thin book. A minor in English taught me that genres are not inevitable. They are cultural choices. Every year I get more comfortable recognizing I'm neurodiverse (substitute your favorite ADHD acronym) and so are many of my best students. Recognizing this makes me a better professor. Math notation, for example, is simply someone else's bad computer code. Don't blame yourself as you struggle to read it, and realize that everyone who succeeds has vivid daydreams that bear no resemblence to the bad code. I loathe nearly every programming book I've ever read. I live in fear that I'll turn the page and be writing a music player. What's that nugget about "never write a language for someone in their first week?" REPL examples always include all beginner "bird track" prompts, when anyone with an aesthetic sense customizes their REPL in the first week to hide all noise and syntax-color output. When I'm feeling an ADHD haze I can barely find the code samples on a programming book page. What I've learned as a professor is that everyone feels this resistance. Some acknowledge it. Planes don't crash because we minimize this resistance in the cockpit. The neurodiverse are the canaries in the mine shaft. I've learned dozens of languages, and bought countless programming books. "The C Programming Language" by Kernighan and Ritchie remains my favorite, a mercifully thin book like "Baby Rudin". Learning a language quickly, one learns how each chess piece moves, and still wonders how to put together programs effectively. Just as the greats in any intellectual discipline insist on only reading original works, the most gifted programmers learn by reading code. I also attempt to learn human languages as a hobby. The great difficulties I experience give me insights into teaching. What is most effective is a staged progression of readers, with parallel text nearby, till one can learn to read unassisted in the language. If the content can be anticipated (such as the wonderfully repetitive "Sapiens" in various translations) all the better. If there's also an audiobook, all the better. A programming book should teach a language through a sequence of small, complete code samples, so clearly delineated that a scuba diver 30 meters deep can work out what's the code, what's the blather. The main activity of reading the book should be puzzling out how each code fragment works. Skip the "word problems" and focus on simple combinatorial tasks that exercise the language.
开篇就点明差异化价值，并花钱请第三方编辑和核查，不要自己校对。
我觉得这里漏了一条建议：一开始就讲清楚你的独特价值。市面上一千本讲 Go 的书，你能带来什么是别人没有的？另一条建议是：请编辑和事实核查。你最不希望的就是把语法糟糕、错误百出的劣质内容放到世上。这篇文章似乎暗示作者自出版时自己做了编辑工作，我认为如果想把结果做到最好，这不值得推荐——花点钱请第三方来做，他们会带来新鲜的视角，帮你看见自己看不到的问题。
ModernMech查看英文原文
I think one piece of advise missing here is: define your value add upfront. There are 1000 books on Go out there. What are you bringing to the table that others don’t? The other piece of advice I have is: hire an editor and fact checker. The last thing you want to do is put substandard quality content out there filled with bad grammar and errors. This post seems to suggest that by self-publishing, the author did the task of editing themselves. I would say this is not advised if you want the best results. Hire a third party to do this work for you instead of doing it yourself. They will bring a fresh perspective to your work and help you see things that you cannot.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选