← #804

Diátaxis：技术文档写作的系统性方法

文章摘要

Diátaxis 是 Daniele Procida 提出的一套技术文档写作框架，网站本身就是这套框架的完整阐述。名字取自古希腊语 δῐᾰ́τᾰξῐς——dia（横跨）加 taxis（安排）。它的核心主张是：文档应当围绕使用者的需求结构来组织，而使用者的需求恰好可以分为四类，对应四种文档形态——教程（tutorials）、操作指南（how-to guides）、技术参考（reference）、解释（explanation）。

框架解决的是文档的三类问题：内容（写什么）、风格（怎么写）、架构（怎么组织）。作者强调它同时服务于文档的创作者和维护者：轻量、易懂、易于应用，不强加实现层面的约束，并给维护者带来一条主动的质量原则，帮助他们有效地思考自己的工作。

为什么恰好是四种？ 这是 Diátaxis 与其他文档分类法的关键区别，也是网站「Foundations」一章的论证核心。作者的说法是：如果只能说「它看起来挺管用」，那它就只是又一个有用的启发式方法；作为一套理论，它必须说明为什么恰好是四种而不是三种或五种。他的推导从「技艺」（craft）出发——Diátaxis 服务的用户是某个技能领域中的实践者，而技能领域由一门技艺定义（使用一门编程语言是技艺，驾驶某型飞机是技艺，当飞行员这件事本身也是技艺）。任何技艺都包含两个正交维度：

行动 / 认知：技艺既包含行动（实践知识，knowing how，我们做什么），也包含认知（理论知识，knowing that，我们想什么）。两者紧密缠绕，但彼此完全不同。
习得 / 应用：实践者与自己的实践之间有两种关系——需要习得它，也需要应用它。「在工作中」（应用技艺的知识和技能）与「在学习中」（获取它们）同样是一对彼此不同却互相缠绕的对应物。

这两个维度构成一张关于技艺领域的完整地图。作者的论证是：只有两个维度，而且它们不只是覆盖了整个领域，它们定义了这个领域——所以必然有四个象限，不可能是三个或五个，这个数字不是任意的。把这张地图翻译到文档上，就得到了四类需求与四类文档的对应：学习的需求由教程满足（用户在习得技艺，文档在告知行动）；目标的需求由操作指南满足（用户在应用技艺，文档在告知行动）；信息的需求由技术参考满足（用户在应用技艺，文档在告知认知）；理解的需求由解释满足（用户在习得技艺，文档在告知认知）。

四种形态的区别。 网站的「地图」一章给出了一张对照表，把四者的差异逐项摊开：教程做的是引介、教育、带路，回答「你能教我……吗？」，面向学习，目的是提供一次学习体验，形式是一堂课；操作指南做的是引导，回答「我该怎么……？」，面向目标，目的是帮助达成某个特定目标，形式是一系列步骤；技术参考做的是陈述、描述、告知，回答「……是什么？」，面向信息，目的是描述这套机器；解释做的是阐明、澄清、讨论，回答「为什么……？」，面向理解，目的是照亮一个主题。作者特别指出，这种组织方式的一个明显好处是它同时提供了对读者的明确预期和对作者的指引：任何一段内容的目的是清楚的，它规定了该怎么写，也指明了该放在哪里。

他还解释了为什么「二维结构」优于「一张清单」：当文档结构不好时，这很少只是结构问题——架构上的缺陷会感染并侵蚀内容。在缺乏清晰、通用的文档架构时，创作者往往试图围绕产品的功能来组织，这即使在单个项目中也很少成功，在一组文档中则会带来剧烈的不一致。而任何有序的内容分类都会有所帮助，但作者常常发现自己要写的某段内容无法很好地落入某个方案给出的类别，或者在重写既有材料时非常吃力——他们会感到这个结构有某种任意性：为什么是这份内容类型清单而不是另一份？如果有另一份清单来竞争，该采用哪个？Diátaxis 的二维推导正是为了回答这个质疑。

指南针。 网站还提供了一个被作者称为「令人惊讶地平庸」的实用工具：地图是好的提醒，但直觉并不总是可靠，作者常常面对「这是哪种文档？」或「这里需要哪种文档？」而没有明显答案，更糟的是直觉有时会立刻给出一个错误答案。Diátaxis 指南针类似于一张真值表或决策树，把二维问题化简为两个问题：行动还是认知？习得还是应用？告知行动 + 习得技能 = 教程；告知行动 + 应用技能 = 操作指南；告知认知 + 应用技能 = 技术参考；告知认知 + 习得技能 = 解释。作者建议在找初始方位时灵活使用这些术语，不要执着于确切的名称。指南针在你觉得自己（或面前的文档）在做某件事、却被某种怀疑或工作中的某种困难困扰时特别有效——它迫使你停下来重新考虑。

网站首页也明确给出了阅读建议：不需要读完整个网站才能理解 Diátaxis 或开始使用它，事实上作者建议你不要那么做——最好的入门方式是读一份简短的入门材料后就直接开始应用。首页还展示了来自 Vonage、Gatsby、Cloudflare 等公司的使用证言，其中 Cloudflare 开发者文档的 Adam Schwartz 说，重新设计文档时 Diátaxis 成了他们信息架构的北极星，不确定新内容该放哪里时就去查这个框架。

HN 评论精华

这条帖子拿到 558 分。它此前多次登上 HN（tedd4u 指出最近一次是 2024 年，那次讨论量最大），所以这轮讨论的重心不在「介绍它是什么」，而在实战经验、与 LLM 的结合，以及一些具体的落地摩擦。框架作者 DanieleProcida 本人也在评论区。

conradludgate 贡献了本轮最有时代特征、也被最多人附和的一条：他以前一直没看出 Diátaxis 的意义，但老实说在 vibe coding 的时候，跟 LLM 说一句「do diataxis」就能拿到质量不错的第一版文档，非常方便。这条下面挤满了同样做法的人：c0rruptbytes 说「一样，对 LLM 生成的第一版文档很好用」；radicalriddler 说几个月前让 Cloudflare 爬了这个站，围绕它做了一组自用的 skill；keeganpoppen 说把这个页面变成一个 skill、然后放它去处理自己所有随手 vibe code 出来的小项目的冲动非常非常强烈；i_v 则描述了一套具体流程：给 agent 一个截图目录，把过程口述一遍，再让它把这些整理成一份指南。
CompoundEyes 给出了一份具体的 agent 落地规则，说明这套框架在 AI 编码工作流里怎么用：他给 agent 的规范要求「从其他文件类型到 reference 类型的链接必须是单向的」以保持 DRY，同时定期把过长的 reference 文件切成更小、更聚焦的文件并从主文件链接过去；他还展示了自己的目录结构（tutorial/、how-to/、reference/、explanation/ 四个顶层目录，每类下面放具体文档）。
rkangel 提供了本轮最扎实的一条使用报告。他和团队为了把一个庞大复杂、积累了历史包袱和大量微妙原因的代码库交付给客户，做了一整套文档。他说 Diátaxis 好得惊人：找出每个页面的标题、把需要覆盖的东西都覆盖到，是要费一番功夫的，但一旦开始写某个页面，就变得非常畅快——你要说什么、用什么「声音」说，都极其清楚。如果是 reference 页面，你就全程描述性，配图表和要点；如果是指南，你就更连贯叙述，但你知道自己只是在传递信息而不是在教学。这让保持连贯和清晰变得容易得多。
Hnrobert42 贡献了本轮最受欢迎的一句玩笑：我劝各位别读这个东西——一旦读了，你会看出所有文档都是有缺陷、令人困惑的一团糟。无知是福。
jamilbk 团队刚花了不少时间按 Diátaxis 重构文档，评价是有帮助但别当成圣经，要记住的关键是每一段内容都应当属于四种类型之一。他给准备重构的人的唯一建议是：动手前先从头到尾读一遍网站，尤其是 complex-hierarchies 那一页。DanieleProcida 亲自回复说：唉，我不喜欢那一页，实际上我已经把它删了，很快就会消失——那里确实有个真实的问题，但那一页处理得不够好，我手上有个好得多的东西在做。（这引发了一串「做好了请发个通知」的请求，其中 zenoprax 顺便问站点有没有 RSS，作者当场加了一个 atom feed 并回复了链接。）zahrevsky 则指出「先从头读一遍」这条建议与网站自己的「Start here」页面开头两句话正好相反——那里明确说你不需要读完这个网站，而且我建议你别这么做。
wonger_ 介绍了另一套文档模型作为对照：Fabrizio 的「七种行为」（seven actions）——人们读文档是为了评估、理解、探索、练习、记忆、发展和排障，通常按这个顺序。他说这套模型相比 Diátaxis 那些被迫的抽象感觉自然得多、显然得多，而他至今仍然搞不清「教程和操作指南到底有什么区别」。rlpb 给了一个不用查资料就能说清的答案：教程是为学习目的而演练一个人为构造的例子，而操作指南提供的是适合在真实世界中执行的说明。ashu1461 补充了自己代码库里的实际例子（「怎么清缓存？」「怎么配置日志？」），并说他喜欢把操作指南与解释/教程分开，因为有时你就是想让工程师照着一个特定流程走，不需要深入。
rjmill 提出了一个非常具体的可用性抱怨：请不要逼我点进「reference」才能到达「API 文档」。他说自己喜欢 Diátaxis，但这场运动的一个副作用是把原本一次点击的文档变成了两次点击（对不知道 API 文档大概归在 reference 下的人来说还更多）——你完全可以保留一个顶级的 API 文档标签页，请不要在「改进」文档的过程中把它藏起来。（他后来补充说自己那条写得比实际感受尖刻，是没睡醒没检查语气。）vanderZwan 说自己一直下意识地把「reference」和 API 文档当同义词，rjmill 指出这正是问题的一部分：一些项目迁移到 Diátaxis 时会建一个叫 reference 的顶层分区，下面只有一个叫 API 的条目，取决于文档主题，这可能需要多点一次。rlpb 从概念上澄清了二者并不同义：每一个 API 调用的规范性查找表是 reference，但一次关于 API 概念的巡览不是（那是 explanation），介绍这个 API 的教程也不是；CLI 参数的规范性查找表同样是 reference。他补了一句立场：在冗余的场合我不主张必须永远采用这种导航结构，人们应该做合理的事——但把不同类别不混在一起仍然是有用的。
mmargenot 提出了框架之外的持久难题：文档很难保持最新，而教程和参考材料（除非由版本化的代码生成）随时间漂移得相当远。他喜欢 Notion 在 wiki 里引入的一个概念性功能——「验证」时间戳，你指定一个期限，过后文档所有者必须重新确认这份文档仍然有效；可惜太容易变成盖橡皮章，也许只有在没有更严格审计就把文档整个下线的情况下才有用。mmyrte 从 R 生态补充了一个把 Diátaxis 三类映射到代码构件、从而让它们可执行的做法：教程实现为 vignettes（在包验证时执行）、how-to 附在 roxygen 文档块里（默认可执行，昂贵或有副作用时禁用）、reference 用 TeX 或 Markdown 格式实现；他说唯一缺的是一种规范的方式来记录实现原理（rationale）。nneonneo 指出 Python 做对的一件事是整个文档站点是版本化的——选 2.7.18 就能拿到 2.7 的文档，一直到教程；Python 的开发流程对文档保持同步也非常谨慎，PEP 流程甚至要求新增或改变语言特性的提案必须有一节明确的「How to Teach This」。
lijok 给出了一句被追问的口号：Diátaxis + ADR + C4 = 文档的三位一体。（Cynddl 追问 ADR 是不是「架构决策记录」、C4 是不是「C4 模型」，并想知道怎么把三者结合起来。）
somewhatrandom9 问它和 Divio 的文档系统有什么区别，随后自己找到了答案（Divio 在前）。DanieleProcida 回应说：基本思想相同，但我在那个早期版本里搞错了很多东西，而那个版本现在已经好几年了。yipinwong 补充了一个实用观点：涉及图示时他仍然参考 Divio 版本，因为 Diátaxis 版本的描述太抽象了。
hahahaa 贡献了另一条高赞玩笑，说的是它「没有」的东西：没有认证、没有培训、没有宣言、没有「你这样做不对」的博文，也没有招聘「Diátaxis 大师」的岗位。d0mine 冷冷补了一句：等它火了再说。
voidhorse 提出了一个偏行业结构的感慨：他对 Diátaxis 本身没意见，但每次它出现都让他难过，因为这提醒了技术写作社区（指职称就是技术写作者的那些人）在推广和分享自己的机构知识上做得有多差，以至于 Diátaxis 远比他们更出名，成了技术圈很多人一想到技术写作就想到的东西。
galaxyLogic 问了一个很自然的问题：四种文档用途的概念看起来很棒，但为什么 Diátaxis 自己的呈现没有清晰地按这四种「视角」组织？marcosdumay 指出左侧菜单里其实是有的——没有 reference，因为这个概念本身不需要 reference，其余三种都在。
DanieleProcida 借这波关注度发了一条呼吁：他正在把 Diátaxis 翻译成其他语言，欢迎参与，并给出了进行中的部分翻译版本的链接。