技术写作与文档2016news.ycombinator.com编辑精选
问 HN：你们团队如何写文档？用什么工具？
Ask HN: How does your team write documentation? What tools do you use?
导读
这是一个 HN 讨论帖，作者请有经验的团队分享他们怎么写文档、优先写哪类文档、用什么工具。值得写作者读的原因在于：它把"写作"放回工程协作的真实语境里——文档写给谁看、放在哪里、怎么迭代，比文笔更决定文档能不能活下去。
可以直接用的写作要点
- 01
先想清楚文档的读者是谁：面向客户端开发者的 API 文档要围绕他们的关切写，而不是围绕实现者的思路写。
- 02
文档只写真正会腐烂又真正有人查的部分：架构和流程值得写，类和方法级别的注释往往写了也没人看。
- 03
把文档放进版本控制（Markdown + git），用分支和补丁走评审，避免"我改好了，大家上线前帮我看看"这种瓶颈。
- 04
用静态站点生成器把纯文本渲染成可检索的页面：搜索能力直接决定别人愿不愿意翻你的文档。
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选