技能 Reference

Diátaxis 文档分类法

适用于 Datarim 管理的仓库和产品站点的文档分类法强制规范:四个正交类别(教程、操作指南、参考、解释)、封闭映射表、豁免清单、反模式定义。由 /dr-init、/dr-optimize 审计、/dr-archive 表面验证加载。

概述

Diátaxis 文档分类法是消费方生态系统中文档结构的权威契约。每个由 Datarim 管理的仓库和产品站点都必须将其文档组织为恰好四个正交类别:教程、操作指南、参考和解释。不得引入新的顶层类别。所有内容类型,包括 FAQ、术语表、故障排查、示例和概述,都必须映射到四个规范类别之一。该强制规范与具体技术栈无关——只要遵守分类法契约,任何静态站点生成器均可使用。

四个类别

  • 教程 — 面向初学者的学习导向类别。读者意图:通过引导式分步体验获取基础知识。典型内容:入门指南、演练、交互式课程、首个应用教程。读者尚不知道要问什么问题。
  • 操作指南 — 面向实践者的任务导向类别。读者意图:解决特定问题或完成具体任务。典型内容:部署指南、测试配方、调试说明、配置步骤。读者知道自己想做什么,并寻求精确的指令。
  • 参考 — 面向查阅的信息导向类别。读者意图:查找确切的参数、API 签名、配置键或规范细节。典型内容:API 文档、命令行标志、配置模式、术语表、数据类型。读者需要准确且完整的事实信息。
  • 解释 — 面向深度理解的理解导向类别。读者意图:理解某事物为何如此运作。典型内容:架构概述、设计决策、概念背景、权衡分析、比较。读者寻求心智模型和上下文理解。

仓库引导布局

<project-root>/documentation/
├── tutorials/
│   └── README.md
├── how-to/
│   ├── README.md
│   ├── testing.md           (*)
│   ├── deployment.md        (*)
│   └── gotchas.md           (*)
├── reference/
│   ├── README.md
│   └── architecture.md      (*)
├── explanation/
│   └── README.md
├── archive/                  (reserved sibling — task archives; not a Diátaxis category)
├── ephemeral/                (transient working material)
│   ├── plans/
│   ├── research/
│   └── reviews/

(*) — 从强制规范之前的扁平脚手架自动映射的遗留存根。幂等性规则:每个文件或目录仅在尚不存在时才创建。

规范根目录(2.49.0+):文档根目录在整个生态系统中为 documentation/——遗留的 docs/ 名称已停用。仍使用 docs/ 的仓库会被标记为漂移,并可通过 /dr-doctor 自行迁移(需选择启用、幂等、可安全回滚)。

保留的同级名称

Diátaxis 类别不得命名为 archive、evolution、release-audit 或 ephemeral。这些是 documentation/ 下的保留同级目录:消费方的任务归档位于 documentation/archive/,与四个产品文档类别并列。一个根目录,清晰分区——产品文档按类别划分,项目历史位于 archive/ 下。

映射表

遗留或提议的类型Diátaxis 类别理由
architecture(默认)reference信息导向——描述系统结构
architecture(原因)explanation理解导向——设计决策、权衡
testinghow-to问题解决——如何运行测试、配置 CI
deploymenthow-to问题解决——如何部署应用
gotchashow-to问题解决——出现典型错误时该怎么做
apireference信息导向——查阅型文档
clireference信息导向——命令签名和标志
configreference信息导向——配置模式和键
conceptsexplanation理解导向——概念背景
designexplanation理解导向——设计理由
tutorialtutorials学习导向——首次端到端体验
quickstarttutorials学习导向——最小引导式设置
faqhow-to 或 explanation(拆分)程序性条目归入 how-to;概念背景归入 explanation
troubleshootinghow-to问题解决——出问题时该怎么做
exampleshow-to 或 reference任务驱动型示例归入 how-to;目录型示例归入 reference
glossaryreference信息导向——定义

这是一个封闭集合。不得将新的文档类型作为单独的顶层类别引入。

反模式

  1. 将 FAQ 作为第五类别。FAQ 是 how-to(问题解决)和 explanation(背景)的混合体。缓解措施:将 FAQ 条目拆分到适当的类别中,并添加交叉链接。
  2. 将示例作为第五类别。示例要么是任务驱动的(how-to),要么是目录型的(reference)。缓解措施:将每个示例放入其语义类别,并附上明确的上下文。
  3. 将架构始终作为参考。描述设计决策、权衡和推理的架构内容必须放在 explanation/ 下。缓解措施:评估读者意图——是事实查阅还是深度理解。
  4. 将索引页作为单独类别。documentation/index.md 是可选的入口点,不是文档类型。缓解措施:索引是导航辅助,不是内容的容器。
  5. 将故障排查作为单独类别。故障排查内容纯粹是 how-to。缓解措施:放在 how-to/ 下,并使用清晰的问题描述标题。
  6. 跨类别内容漂移。随着时间推移,内容可能积累来自其他类别的材料。缓解措施:在评审期间,对照类别定义检查每个文件,必要时进行拆分。

豁免清单

  • 仅用于研究的仓库(无需面向用户的文档)。
  • 仅用于归档的仓库(快照、备份、历史记录)。
  • 使用 PARA 结构的 Obsidian 库。
  • 单文件收件箱笔记或草稿文档(临时、非公开)。
  • 在强制规范软批准日期之前创建的遗留仓库。
  • 临时草稿路径(temp/*、scratch/*、test-scaffold/*)。

操作员覆盖:任何仓库均可在豁免登记表中被明确标记为有意豁免。

技术栈无关边界

本强制规范不得指定任何具体的 SSG 或 CMS(Docusaurus、Mintlify、VitePress、Hugo、Sphinx)。文档生成器的选择因项目而异,不在分类法强制规范的范围内。

品牌层

品牌层不在范围内:Datarim 定义分类法结构(四个类别加豁免)。标语、页脚和品牌资产因生态系统而异,由消费方自己的 AGENTS.md 定义。

漂移检测

强制规范合规性由 /dr-optimize 第 6 步使用文件系统存在性检查(阈值:3 个文档文件和全部 4 个类别目录)进行验证。检测是软性的——仅警告,不阻塞构建。未来的硬性 CI 门禁(可执行的退出码 1)推迟到 INFRA-* 待办事项,待强制规范在至少三个活跃消费方上采用后激活。