技术写作与文档2018two-wrongs.com编辑精选
技术写作：向 Kernighan 学习
Technical Writing: Learning from Kernighan
导读
这篇文章分析 Kernighan（《The C Programming Language》《The AWK Programming Language》作者）的技术写作手法：一上来就给具体例子、极简克制、结构分层。对写作者的价值在于，它把"怎么把复杂的东西讲清楚"拆成了可模仿的具体做法，而不只是赞美文笔好。
可以直接用的写作要点
- 01
开篇直接给具体例子（输入、程序、预期输出），把理论讨论和安装说明放到后面，让读者第一页就看到成果。
- 02
先让读者动手、积累具体经验，再补解释——解释要在读者有过体验之后才讲得通，顺序反过来效果差很多。
- 03
用一个贯穿全书的示例（如逐步搭建一个通讯录程序）承载知识点，每加一个功能就顺带展示一个通用技巧。
- 04
把新内容和读者已知的东西挂钩；整体结构可按"入门—完整描述—进阶技巧—参考手册"分层。
- 05
注意：极简未必是普适原则，也可能只是作者的个人风格，别把它当成技术写作的硬性标准。
HN 评论精选
awk 教程直接把读者扔进使用场景：没有理论铺垫，没有安装说明，第一眼看到的就是输入示例和一段处理它的短程序，第一页就给出预期输出。婴儿学语言靠听人说话，也就是靠例子；没有人是靠理论论述和语法图学会一门语言的。这反直觉——你会以为有人讲解比丢一堆例子学得更好，但事实是我们靠例子和练习学习。最终你确实需要解释来补全理解，但在你亲手弄脏手之前，解释是没意义的。所以对任何想教东西的人都是一课：开头简短介绍可以，但尽快进入具体例子。
combatentropy查看英文原文
> The tutorial throws the user straight into the experience of using awk. There is no theoretical discussion first; there are no installation instructions; the first thing you see is an input example and a short program doing something with that input. They even get to the expected output on the very first page. Babies learn a language by hearing you talk. In other words, by example. No one has become fluent in a language through theoretical discourse and grammatical diagrams. That is counterintuitive. You would think you would learn better by having someone explain it to you, instead of throwing a mish-mash of examples your way. But that's not the truth. The truth is we learn by example and practice. Eventually you want the explanations, to round out your understanding. But it doesn't make sense until you have got your hands dirty. So that's a lesson for anyone wanting to teach anything. It's okay to have a little introduction, but try to get to concrete examples as soon as possible.
Kernighan 还写过一本很好的书《Understand the Digital World》，面向非技术读者介绍计算机和网络技术。它讲到二进制、汇编和几种高级语言，同时强调计算机能做什么、不能做什么的整体概念，还包含相当新的网络（高层视角）、在线隐私、加密与安全讨论。他用简洁明晰的文字把高度技术性的概念讲给毫无计算机背景的读者，这种能力非常惊人。
mediocrejoker查看英文原文
Kernighan also has a very well written book called Understand the Digital World, which is an introductions to computer and network technology for a non-technical person. It touches on binary, assembly language, and a few higher level programming languages while emphasizing the general idea of what a computer can and cannot do. It also includes very up to date discussions of how networks work (at a high level) and online privacy and, encryption and security. His ability to explain highly technical concepts to someone with no assumed computing background in concise and lucid prose is really impressive.
我再推荐一本技术写作的好书：《Unix Shell Programming》。它同样遵循"入门—完整描述（受篇幅所限未必穷尽）—中级—高级技巧—参考资料"的结构。全书贯穿的例子是做一个叫 rolo（Rolodex 的谐音）的通讯录程序，作者们在逐步添加功能的同时展示普遍适用的实用技巧，做得很好。第三版我没读过，但第二版现在肯定有点过时了。尽管如此，它写得清楚、结构良好，是 shell 大部分常用概念的好入门。
mauvehaus查看英文原文
I'll call out another book for being a great piece of technical writing: Unix Shell Programming[0]. It similarly follows the structure of introduction, complete description (if not full-depth out of necessity), intermediate, and advanced techniques, and some reference material. The running example throughout the book is to build an address book program called "rolo" (Rolodex, get it?), and the authors do a nice job of progressively building the features while illustrating useful techniques that are generally applicable. I've not read the 3rd edition, but I can vouch for the fact that the 2nd would be getting a little dated by now. Still, it's well-written, well-structured, and a great introduction to most of the shell concepts that you use. [0] https://www.amazon.com/Unix-Shell-Programming-Stephen-Kochan/dp/0672324903
我觉得这是很好的建议。从我读过的少量内容看，这些书另一件做得好的事，是把读者已经会的东西和正在教的东西连接起来。我唯一的小异议是：极简恐怕更多是口味问题，而不是一条普遍适用的扎实技术写作原则。我从极简的书里学到很多，也从带截图或全彩插图的书里学到很多。这不是说极简对 Kernighan 不管用，只是它不像其他原则那样可推广。
actuallyalys查看英文原文
I think this is excellent advice. From the small amounts I've read, the other thing these books do well is connect what the reader already knows to what's being taught. My only quibble is that I suspect minimalism is more a matter of taste than a widely applicable principle of solid technical writing. I've learned a lot from minimal books, but I've also learned a lot from books that incorporate screen shots or full-color illustrations. This isn't to say minimalism didn't work well for Kernighan-just that it's not as generalizable as the other principles. FYI, You can read both the The C Programming Language [0] and The AWK Programming Language [1] at the Internet Archive. [0]: https://archive.org/details/TheCProgrammingLanguageFirstEdition [1]: https://archive.org/details/awkprogrammingla00ahoa
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选