技术写作与文档2024diataxis.fr编辑精选
Diátaxis——技术文档编写的系统化方法
Diátaxis – A systematic approach to technical documentation authoring
导读
Diátaxis 是一套把技术文档按「教程、操作指南、参考、解释」四类拆分的写作框架，核心是让每一篇文档只服务一种读者需求、只承担一种写作任务。对写作者来说，它提供了一把可复用的尺子：先判断你在写的是「教人学会」「帮人做完」「供人查阅」还是「帮人理解」，再决定语气、结构和详略，避免把四种东西混成一篇四不像的长文。
可以直接用的写作要点
- 01
动笔前先给文章定性：是教程（带新手一步步学会）、操作指南（帮有基础的人完成具体任务）、参考（供人快速查阅事实）还是解释（讲清原理与背景），一篇只写一种。
- 02
教程要替读者做决定、保证每一步都能成功；操作指南则假设读者已有基础，只给达成目标的路径，不重复教学。
- 03
参考文档追求准确、完整、结构一致，方便跳读检索；解释性文字才允许铺陈来龙去脉、权衡与设计动机。
- 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 条写作要点编辑精选