필사 모드: 为什么 Diátaxis 会被误解成四个文件夹 —— 一篇文档里混两种模式为什么会塌

• 如果你曾经打开一份教程、三十分钟后就关掉了页面
• 建四个文件夹并不算落地
• 之所以是四个，是因为有两条轴
• 罗盘 —— 只对一个段落抛出两个问题
• 最常见的混淆发生在教程与操作指南之间
• 两种状态要的恰好相反
• 说明渗进参考的那条路径
• 这周就能做的事 —— 一个段落，一次提交
• 小结与出处

如果你曾经打开一份教程、三十分钟后就关掉了页面

假设你打开了一个第一次用的库的官方教程。第 1 条让你安装，第 2 条让你跑示例。到这里都还好。可第 3 条突然是这么开头的：「这个值可以用三种方式配置，生产环境推荐第二种。」在你根本不知道三选一该选哪个的状态下，被丢过来三个选项。第 4 条冒出两段内部原理，第 5 条又回到命令行。

这份文档没有装错误信息。句子也都通顺。可读的人在三十分钟左右就把页面关了。文档团队得知这件事的途径，通常是「文档不够」这样的反馈，而收到反馈之后做的事，通常是往里加更多内容。于是下一个人二十五分钟就关掉了。

建四个文件夹并不算落地

给这个问题命名的是 Diátaxis。它把文档分成教程、操作指南、参考、说明四种。它广为人知、也被广泛引用，但在真实团队里的落地大多止步于此：在文档仓库里建四个文件夹，把现有文档挪进去，完事。

可框架的作者一方明确劝阻这种做法。Diátaxis 的工作流文档说，开始时并不需要把文档分成四个区块，而对于建四个空空如也的章节这件事，它把话钉死了：不要这么做。结构是改进的结果、之后才浮现出来的东西，而不是为了改进先强加上去的东西。作者对此的说法是，Diátaxis 是从内部改变文档的结构。

之所以是四个，是因为有两条轴

为什么偏偏是四个，这很重要。如果说不出为什么不是三个或五个，那它就只是一种方便的分类，而方便的分类在一篇含混的文档面前毫无用处。

Diátaxis 的基础文档把使用某项技能的人放在两条轴上。一条是行动与认知。任何一项技能，都同时包含关于「要做什么」的实践之知，和关于「什么是真的」的理论之知。另一条是习得与应用。人要么正在学一项技能，要么正在使用已经学会的技能。换成「学习状态」和「工作状态」也一样。

由于两条轴彼此独立，象限必然是四个。学习的需求由教程承担，达成目标的需求由操作指南承担，获取信息的需求由参考承担，理解的需求由说明承担。四不是随手挑出来的数字，而是能不留缝隙地覆盖这片领域的最小个数。

罗盘 —— 只对一个段落抛出两个问题

地图好记，但面对含混的文档，直觉经常出错。所以 Diátaxis 另外准备了一张叫罗盘的判定表。要问的只有两件事。

重要的是，这张表不只能用在文档层面，也能用在段落层面。事实上 Diátaxis 建议你连句子和词的层面都拿来套一遍。把前面那份教程的第 3 条放进这张表，答案立刻就出来了。罗列三种配置方式的部分处理的是认知、面向的是工作中的人，所以它是参考。生产环境的推荐理由属于认知、面向的是学习中的人，所以它是说明。一篇文档里装了三种模式。

最常见的混淆发生在教程与操作指南之间

Diátaxis 指出，软件文档中最常见的混淆，就是教程与操作指南之间的混淆。原因很简单：两者外观几乎一样。都摆出编好号的步骤，都承诺按顺序照做就会成功，也都对不动手的读者毫无用处。

区别不在形式，而在所服务的需求。教程服务的是正在学习的人，操作指南服务的是正在工作的人。这里常冒出来的第二个误解，是把教程当基础、把操作指南当进阶，这也是错的。文档原文说，操作指南可以、而且应该覆盖基础性的步骤；反过来，为极其熟练的人准备的高难度教程也是可能的。分界线不是难度，而是读者在学习还是在工作。

两种状态要的恰好相反

混起来会塌的原因就从这里来。两种状态所要求的东西彼此互斥。

• 选项：教程不制造岔路。给一个还没有能力做选择的人抛出选项，他当场就会停下。反过来，操作指南必须分岔。现实里条件五花八门，没有按条件分支的指南，到了现场就没用。
• 责任：教程里出了问题，那是作者的过错。你必须把环境控制好，让学习者无法失败。而在操作指南里，用户为自己的处境负责。
• 安全：教程必须允许随时退回到最初。操作指南给不了这种保证，一次就得做对的作业很常见。
• 说明：Diátaxis 直接断言，教程不是用来解释的地方。它还补充说，想把理由讲出来这股冲动，是教书的人最难战胜的诱惑。借用原文的表述，教学的第一条规则是「don't try to teach」。

所以，当你把选项塞进教程第 3 条的那一刻，这份文档对两类读者都变差了。它逼着学习中的人做决定，又没能把工作中的人需要的分支全都展示出来。

说明渗进参考的那条路径

剩下两种模式之间也会发生同样的事，只是这一侧安静得多。Diátaxis 把这条路径讲得很具体。往参考里放示例本身是正当的。问题在于示例很有趣，写着写着就不断向「为什么会这样」和「这么做又会怎样」蔓延过去。

结果是两边都吃亏。参考被岔路挡住，变得难找；说明寄人篱下，也没法好好展开。判定标准依然只有一条：这是工作过程中翻开来看的东西，还是从工作里退一步、思考时才需要的东西。

分不清是参考还是说明的时候，还有一条好用的经验法则。如果它无聊、看完记不住，那多半是参考；能整理成列表和表格的，通常也是参考。反过来，如果它像是有人在散步时问起来、你可以拿来回答的那种话，那就是说明。

这周就能做的事 —— 一个段落，一次提交

Diátaxis 的工作方式是站在「别画大图」那一边的。它说，与其制定计划然后一次性搬迁，不如重复下面四个步骤。

1. 随便挑一个。 别到处去找问题，就看现在打开着的文件、刚刚读过的那一页。没有的话就随机挑。
2. 推敲一下。 比一整页更小才好。一个段落、甚至一个句子都行。这是为哪种需求存在的，它把这个需求满足得怎么样，加点什么、挪点什么、删点什么会更好。
3. 只定一件事。 挑出此刻就能构成改进的下一个动作，就一个。
4. 做完就收。 把那一件做掉，立刻提交或发布。不要觉得还得再多做点。

搬到自己的团队，可以这样开始。打开这周被打开次数最多的那一份文档，对每个段落抛出前面罗盘的那两个问题，给它打标签。如果某份文档出现了两种以上的标签，就只挑其中一种搬到另一份文档里，原地只留一个链接。此时如果还没有可以搬过去的文档，那就不要建空文件夹，而是建一份文档。这个差别，正是避开前面被劝阻的那个错误的地方。

文档永远不会结束，这一点不会变。Diátaxis 把文档比作生长中的植物，说它不会终结，但在每一个阶段都可以是完整的。这周只搬了一个段落的文档，在那个状态下也是完整的。

小结与出处

压缩成一句话就是：Diátaxis 不是给文档分类的规则，而是追问一段文字服务于谁、服务于他的哪种状态的规则。四个文件夹替你回答不了这个问题。

• Diátaxis 官方网站 —— 框架本体。下面各项都是这个站点上的文档。
• Foundations —— 行动与认知、习得与应用这两条轴，以及象限为什么是四个
• The compass —— 用两个问题作判定的表
• The difference between a tutorial and how-to guide —— 选项、责任、安全、说明上的对照，以及基础与进阶这个误解
• The difference between reference and explanation —— 说明渗进参考的路径与经验法则
• Diátaxis as a guide to work —— 不要建空章节的警告、四步工作循环、完整与终结的区分
• Tutorials —— 不要试图去教的原则，以及「说明」这个诱惑
• 文档原文可以在 evildmp/diataxis-documentation-framework 仓库里直接读到。本文的引用与摘要，都是直接核对该仓库原文得来的。