技术写作与文档2021blog.klipse.tech编辑精选
写第一本技术书时我学到的事
Things I learned writing my first technical book
导读
这是一篇技术书作者复盘自己写第一本书的经验总结，核心讲如何把枯燥的技术内容组织成读者愿意读下去的东西。对写作者的价值在于：它谈的是写作中那些通用的问题——读者视角、叙事化取舍、结构与大纲的转换。评论区补充了编辑的作用和一个重要的取舍提醒。
可以直接用的写作要点
- 01
让读者觉得自己聪明，而不是觉得作者聪明：写清楚的目的是让读者有获得感，不是展示自己的水平。
- 02
先回答“为什么”，再讲“是什么”，最后才讲“怎么做”；这个优先级对技术文档、源码注释同样适用。
- 03
用人物、对话和故事包装技术内容能显著提高可读性，但要接受一个代价：书会变得没那么“高密度”。
- 04
思维导图容易膨胀成一张过度连接的网，落笔前必须把它转成线性大纲，否则读者跟不上。
- 05
好编辑的价值被低估了：被严格编辑过的文字，往往是你能写出的最好的文字。
HN 评论精选
好编辑能大幅提升文字质量，这个环节常被写作者忽略。
这份清单很好！我最喜欢的一句是：“平庸的作者让读者觉得作者聪明，好的作者让读者觉得读者聪明。”另外我很惊讶文中完全没提编辑的重要性——我只能假设编辑在今天已经不像过去那么被看重了。我母亲是科技编辑，下手极狠。我曾写过一本400页的书（最终没出版），她帮我编辑，那可能是我写过最完美的文字（只是等它改好时，内容已经过时、技术上也不相关了）。
ChrisMarshallNY查看英文原文
That’s a good list! My fave: > An average writer makes the reader think the author is smart. A good writer makes the reader think the reader is smart. I am quite surprised to see no mention of the importance of an editor. I have to assume that they are no longer as important, these days, as they once were. My mother was a scientific editor, and she was brutal. I once wrote a 400-page book (that was never published). She edited it for me, and it may be the most perfect prose I’ve ever produced (but it was out of date and technically irrelevant, by the time it was ready).
“为什么>是什么>怎么做”的优先级也适用于注释和文档。
“为什么”比“是什么”重要，“是什么”比“怎么做”重要——这个原则用在源码注释和内部文档上也非常适用。
wongarsu查看英文原文
>The “why” is more important than the “what”. >The “what” is more important than the “how”. This also feels very applicable to comments in source code, or internal documentation in general
思维导图易膨胀成网状，如何转成线性结构是关键难点。
关于“思维导图是很好的可视化工具，要聪明地用”，我很好奇具体做法。因为我的经验是，思维导图很快会长成一张巨大、过度连接的图，很难转换成书或博客文章需要的那种线性结构。作者的流程是怎么把这两者衔接起来的？
tibbar查看英文原文
> Mind maps are a great visualization tool. Use them smartly I’m curious about this, since my experience with mind maps is that they rapidly grow into giant overly-connected graphs that are very difficult to translate to the sort of linear structure a book or blog post needs. What is OP’s workflow for connecting the two?
故事化写法提升可读性，代价是牺牲信息密度。
（自荐一下）文中说“让内容变得有趣的一个办法，是把材料当故事讲，加入虚构人物和一点戏剧性”。我正在收尾新书《Head First Git》，说实话，写到一半我才真正意识到这一点有多重要。Head First 系列用非常口语化的语气，充满人物和轻松的小故事来讲技术，还有大量戏剧化情节、插图和练习来巩固概念。我接这个项目是因为自认为对 Git 非常熟，但尽管如此，这本书仍是我做过最难的事之一，主要因为每一章都需要一条叙事线、虚构人物、对话和他们要解决的问题，同时还得守住技术主题。写这本书肯定会影响我今后讲课和演讲的方式，作者说得完全对——用“人”的故事来吸引读者，确实让书更有趣、更好消化。但反过来说，这也让书的密度变低了。
raju查看英文原文
*shameless plug* > A possible way to make things interesting is to teach the material as a story with fiction characters and a bit of drama. I am wrapping up the final touches on my latest book, Head First Git[1][2] and I will admit that it wasn't till I was midway through the book when it _really_ dawned on me on how important this is. Some of you might be familiar with the Head First series (if you are not, Head First Design Patterns [3] is a great place to start). It uses a very conversational tone, filled with characters, and lighthearted stories to explain technical issues. Lots of drama, visuals and exercises to help cement ideas. I took on the project because I feel like I am intimately familiar with Git. Despite that, this book is one of the hardest things I've ever done, mostly because every chapter needs a narrative, with fictional characters, conversations, and problems they are aiming to solve, all while keeping a technical topic in scope. I know that writing this book has certainly influenced how I might teach or speak on a topic in the future, but the OP is absolutely right—engaging the reader by making the stories about "people" certainly makes the book more interesting and easier to digest. On the flip-side, it makes the book less _dense_. [1] https://www.amazon.com/Head-First-Git-Learners-Understanding/dp/1492092517 [2] https://learning.oreilly.com/library/view/head-first-git/9781492092506/ [3] https://www.amazon.com/Head-First-Design-Patterns-Object-Oriented/dp/149207800X (edited for formatting)
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选