2026年7月23日

diataxis-docs 技能——四大类别,绝无例外

diataxis-docs 技能如何在每个由 Datarim 管理的仓库中强制执行 Diátaxis 分类法,将每种文档类型映射到四个正交类别之一,并阻止那些会随时间侵蚀该分类法的反模式。

文档往往会为每种内容类型都积累出一个类别:一个 FAQ 页面、一个示例页面、一个故障排查页面,最终还会有一个用来放置无处可归之物的页面。diataxis-docs 技能强制执行一种不同的方法:四个类别,每个类别由读者意图定义,并采用一套封闭映射,将每种文档类型恰好归入其中之一。

四大类别

教程是学习导向的。读者是初学者,尚不知道要问什么问题,需要一份引导式的端到端演练来建立基础知识。操作指南是任务导向的:读者知道自己想做什么,需要精确的指令来完成某个具体、明确的任务。参考材料是查阅导向的:API 签名、配置键、命令标志以及确切的参数值。解释是理解导向的:设计决策、架构权衡以及概念背景,帮助读者建立关于系统为何如此运作的心智模型。

参考与解释之间的区分是常见的混淆来源。架构内容可以归入任一类别。如果读者查阅的是关于系统结构的事实,该内容就是参考。如果读者想要理解结构背后的理由,该内容就是解释。该技能通过一张映射表将这一判断明确化。

仓库布局

在 Datarim 下搭建的每个新仓库都会获得一个 docs/ 目录,其中包含四个子目录:tutorials/、how-to/、reference/ 和 explanation/。每个子目录都包含一个 README.md 存根。一个可选的 ephemeral/ 目录用于存放临时工作材料——计划、研究笔记和评审——这些不是文档,也不需要 Diátaxis 类别。引导过程是幂等的:仅在目录和文件尚不存在时才创建它们。

该技能在设计上与技术栈无关。它不指定任何静态站点生成器,也不指定任何 CMS。分类法是强制要求;工具选择属于各个项目。

该技能阻止的反模式

该技能中列出了六种具体的反模式。将 FAQ 作为第五个类别是其中之一:FAQ 条目要么是操作指南(过程步骤),要么是解释(背景上下文),正确的修复方式是拆分它们,而不是新增一个类别。将示例作为第五个类别是另一种:任务驱动的示例属于操作指南,目录式示例属于参考。第三种是将所有架构内容都视为参考——解释理由的设计决策内容属于解释。

内置于 /dr-optimize 第 6 步的漂移检测会检查四个目录是否都存在,以及是否至少存在三个文档文件。该检查是软性的——它会发出警告,但不会阻止构建。一个未来的硬性 CI 门禁已列入待办事项,待该强制要求至少有三个实际使用方后再启用。

豁免

仅用于研究的仓库、仅用于归档的仓库、使用 PARA 结构的 Obsidian 库,以及在该强制要求软批准日期之前创建的遗留仓库均获豁免。操作员还可以在 datarim/docs/exemptions.json 中将任何仓库明确标记为豁免,这会将其从漂移检测中移除,直到该覆盖被撤销。

该技能所实现的规范是 diataxis.fr 上的公开 Diátaxis 框架。阅读什么是 Datarim 以了解更广泛的项目背景,或阅读 /dr-optimize 命令文章 以了解漂移检测器在审计工作流中的位置。