技术写作与文档2021apress.com编辑精选
《写给开发者的文档》：工程师的技术写作实战指南
Docs for Developers: An Engineer’s Field Guide to Technical Writing
导读
这是一本面向开发者的技术写作实战指南（Apress 出版），讨论如何把文档写得清晰、可维护。对写作者的价值在于：评论里给出了被广泛引用的文档分类框架（Divio 四象限），以及关于“写作清晰＝思路清晰”“技术写作是专业工作”的两种重要视角，可用来反思自己的说明类写作。
可以直接用的写作要点
- 01
按读者目标给文档分四类——教程（学习导向）、操作指南（解决问题导向）、解释（理解原理导向）、参考（查信息导向）——写之前先确定自己在写哪一类，避免把四类混成一篇。
- 02
套用这个框架时，关键不是分类本身，而是让作者先想清楚“读者读完要达成什么目标、得到什么结果”，再决定写法。
- 03
把写作当作思考的检验：写不清楚往往说明还没想清楚，改写文字的过程也就是理清逻辑的过程。
- 04
别默认让开发者顺手写文档就能写好——优秀文档通常由专职技术写作者与工程师协作完成，个人写作时也应给自己留出专门的写作与修改时间。
HN 评论精选
用目标与场景四象限给文档分类，先定类型再动笔。
推荐 Divio 的“文档统一理论”：用两个维度（实践步骤↔理论知识、学习时有用↔工作时有用）划出四类文档——教程（学习导向）、操作指南（问题导向）、解释（理解导向）、参考（信息导向）。该框架的价值在于让作者从“读者想要达成的目标和结果”出发思考文档。
infogulch查看英文原文
I like linking to this site [0], the "The Grand Unified Theory of Documentation" that describes four categories of documentation that fill out a 2D space of potential docs value: the practical steps <-> theoretical knowledge dimension, and the useful when studying <-> useful when working dimension. * Tutorials - Learning-oriented - (practical/studying) * How To Guides - Problem-oriented - (practical/working) * Explanations - Understanding-oriented - (theoretical/studying) * Reference - Information-oriented - (theoretical/working) It passed through HN ~9 months ago [1], where kaycebasques stated, "I think the key breakthrough with Divio's framework is getting authors to think about docs in terms of desired goals and outcomes: learning-oriented, problem-oriented, etc." [0]: https://documentation.divio.com [1]: https://news.ycombinator.com/item?id=26002656
写作体现思考，但好文档需要专职写作与工程师协作，而非人人兼职。
清晰的写作确实反映清晰的思考，也能带来清晰的编程。但技术写作是一份需要真实投入的专业工作；让所有开发者包揽文档，和有些公司迷信招“全栈工程师”是同一种管理思维。我待过文档真正出色的地方，都是专职技术写作者与工程师协作的。
teeray查看英文原文
I do think clear writing is an indication of clear thinking, which leads to clear programming. However, technical writing is a real job with real work involved. To make developers write all the documentation is the same management mentality some places have about hiring “full-stack engineers.” The places I’ve worked at with truly excellent documentation had full-time technical writers that collaborated with engineers.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选