技术写作与文档2022diataxis.fr编辑精选
Diátaxis：技术文档写作的系统化框架
Diátaxis: A systematic framework for technical documentation authoring
导读
Diátaxis 是一套系统化的技术文档写作框架，主张按「用户是在学习还是在工作」和「内容是实践还是理论」两个维度，把文档拆成教程、操作指南、参考和解释四种类型。对写作者来说，它提供的不是文风技巧，而是一种先判断「读者此刻需要什么」再决定写法的思路，可迁移到教程、说明文和知识类写作中。
可以直接用的写作要点
- 01
动笔前先问读者是「学习」还是「干活」：学习型内容重在引导入门，工作型内容重在快速解决问题，两者不要混在一篇里。
- 02
把「步骤」(教程、操作指南)和「概念解释」「参数清单」分开写，混在一起会让读者既学不进去也查不到东西。
- 03
每篇文档只服务一种需求;想补充背景知识就另起一篇并链接过去，而不是在操作步骤中间插大段原理。
- 04
用这套四分法给自己的旧文档做一次盘点，找出缺失的类型(通常是「解释」)或混杂不清的部分。
HN 评论精选
这套四分法符合直觉，很多团队已在无意中实践，框架的价值在于给它命名并系统化。
也许是法国文化的产物，但因为 Gorgonia 项目有不少法国贡献者，我们实际上就是按这种方式组织文档的——只是第一次知道这个框架还有名字。
chewxy查看英文原文
Perhaps it's a product of French culture, but because Gorgonia[0] has a number of French contributors, this was actually the way we structured our documentation. But this is the first time I've heard of the name of the framework. [0]: https://gorgonia.org
补充了同一框架的另一个（更早的）出处，可对照阅读。
documentation.divio.com 讲的似乎是同一套体系。
Kinrany查看英文原文
https://documentation.divio.com/ seems to be talking about the same system.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选