技术写作与文档2021cscalfani.medium.com编辑精选
如何写一本编程书
How to Write a Programming Book
导读
这是程序员兼写作教练 CSCalfani 关于「怎么写编程书」的经验总结，核心主张是先抛出问题再给答案，反对教科书式的循序渐进跳崖（第 3 章直接上微积分）。对写作者来说，它讲的不只是技术写作，而是所有教学型、说明型写作共同的节奏问题：读者的困惑从哪里来、什么时候该给答案。
可以直接用的写作要点
- 01
先让读者感到「我有一个问题」，再给解法；没有痛点的知识，读者记不住也用不上。
- 02
别把「显而易见」当理所当然：每一行代码、每一个步骤都要交代清楚，作者眼里的常识往往是初学者的悬崖。
- 03
用整体感带出细节：先让读者抓住你想表达的意思，让他自己推测含义，比逐条塞定义更能留下长期记忆。
- 04
警惕难度断崖：从 ABC 直接跳到微积分是常见的失败模式，要检查每个新概念之前读者是否已具备必要铺垫。
HN 评论精选
先制造问题、留出思考空间，读者才会真正在乎答案。
「永远不要给学生一个他还没有的问题的答案。」这让我想起刚上高中时的顿悟：学校不过是一堆没人问过的问题的答案。并不是我不想学，而是不想在与我当下状态完全无关的时间点被硬塞知识。大学里老师确实会先抛出现实问题，但下一张幻灯片立刻揭晓答案，把乐趣全毁了——我通常捂住耳朵自己先想。别人的解法，只有在我自己投入努力之后才会变得有趣，那时才能拿来对比。
andai查看英文原文
3. Never give a student a solution to a problem they don’t have. This reminds me of when I just started high school and realized, "school is just a bunch of answers to questions nobody asked." It's not that I didn't want to learn, nor even that I didn't want to learn those exact things -- just not have them fed to me at arbitrary intervals with total disregard for my actual state of mind. (The original Dalton school mine was inspired by did this right, over 100 years ago, but most of the methods -- ie. letting kids learn what they actually care about, when it interests them most -- are illegal in my country.) As for presenting the question first, at university this was often done, they would present us with some real world problem -- but then they would spoil the fun by instantly revealing the solution on the next slide! I like figuring things out, so in those moments I'd usually cover my ears and try to figure it out on my own. Somebody else's solution only becomes interesting to me once I've invested the effort to make my own, and then I can compare and contrast.
逐行解释代码，并认真对待装环境这类「低级」障碍。
我讨厌这种难度跳崖，但大多数作者都这么干。我买过一本号称循序渐进的 Rust「入门」书，突然就出现几十行没有解释的代码，还注释着「这很容易懂」——并不容易，我放弃了这本书。作为写过几本编程书的人，我的经验是：一、解释每一行代码，你觉得显然的东西对别人并不显然，除非对方会读心术。二、初学者会卡在最基础的地方，比如 Python 装库，我有多年经验有时都会被装库搞到崩溃。我作为学生也经历过：跟着教程试一个 JS 库，花一小时配 npm、跟版本打架（这个库只兼容老版本 npm），还得装 Python 2.7——最后我放弃了。这就是初学者的感受，而且你一抱怨就会被要求「去读手册」。
shantnutiwari查看英文原文
good article. >>It’s like, Chapter 1: Learning Your A,B,Cs. Chapter 2: >>Learning Your 1,2,3s. Chapter 3: Differential Calculus! I hate this, but most authors do it. I recently bought a "beginner" book on Rust that promised to take things slow. And then suddenly, bam! There was dozens of lines of unexplained code, with the comment "This is easy to follow". No, it wasnt. I gave up on that book. As someone who has written a few programming books, my experience is: 1. Explain every, yes, every single line of code. Whats so obvious to you isnt obivous to anyone else, unless they are Professor Charles Xavier and can read your mind. 2. Beginners get stuck in the most basic of things. In Python, my field, it is as simple as installing libraries. Even though I have many years expereince, sometimes just installing a library can leave me in tears. I recently had an expereince of this from the other side(as a student)-- wanted to try out a Javascript library ,as I was following a tutorial. Ended up spending an hour configuring npm, fighting with different versions(as the library only worked with an old version of npm, and I had to figure out how to install multiple npm versions) , installing Python 2.7 (why the hell does a JS library need Python 2.7? Who knows?) Ultimately, just gave it up. This is how beginners feel-- and I know from experience if you ask or complain about this, you will be attacked, asked to RTFM etc etc. "How hard can it be to install a library? Do a pip or npm install! Do your research before asking questions." So beginners can get stuck and quit at the most basic of things. And beginner just doesnt mean someone new to programming -- I was the beginner when learning JS (and still am).
先给整体语境让读者自己推断，比预先定义每个术语更有学习效果。
很好的文章。我现在也是老师，想在他「先问题后答案」的基础上补一点：我教英语，发现把每个要用的词都先下定义，不如先给学生我想表达的整体意思，让他们的脑子自己去琢磨含义。这对某些学生确实更挫折，但当你能听懂一段话的大意时，你的大脑会比被喂现成答案时运转得努力得多，长期来看对学习更有利。
magpi3查看英文原文
A really nice article. I am a teacher now, too, and I would add this to his notion of giving a problem before a solution. I teach English, and I have learned that giving students definitions to every word I am going to use is not as beneficial is giving them the sense of what I am trying to say and letting their minds figure out the meaning. This is obviously more frustrating for some students, but when you understand the general meaning of a something you hear, I really believe your mind starts to work a lot harder than if you are spoon fed things, which is a lot more beneficial to learning in the long run.
初学者到进阶之间缺的是关键线索，写作应专门补上这一层。
九十年代读完物理学位后，我一直想当教育者、写书去填补初学者和专家之间的空白——难点在于自己要先成为专家，并理解那段空白里的本质。我通常只需要一条线索就能从入门跨到中级，但很少有人提供这些线索，而且它们可能因人而异。
jkmcf查看英文原文
Since surviving my Physics degree in the 90s, I wanted to be an educator and write books that filled in the gaps between beginner and expert -- the problem was becoming an expert and understanding the essence of things in that gap. I generally just need that clue to go from beginner to intermediate, but no one usually provides those clues (and they might be different for everyone!)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选