夜雨聆风导语
Diátaxis 是一个面向技术文档写作与信息架构的框架，核心主张很简单：用户读文档时并不是只有一种需求。有人在学习，有人在完成任务，有人在查事实，也有人在寻找背景理解。把这些需求混在一起，文档就会变成“什么都有、但哪里都不顺手”的资料堆；把它们分开，文档才会真正可用。
核心内容
Diátaxis 将技术文档划分为四类：教程、操作指南、参考资料、解释说明。这不是按作者心情分类，而是按用户当下的需求分类。教程服务于“学习”，它像一堂课，带着初学者完成一个可控、完整、能带来信心的实践体验。教程的重点不是把所有概念讲透，而是让用户通过动手获得经验，因此应该少解释、少分岔、尽早给出可见结果。
操作指南服务于“工作”，目标是帮助已经具备基础能力的用户解决一个真实问题。它关注具体目标、实际约束和可执行步骤，例如如何配置某项策略、如何排查某类故障。与教程不同，操作指南不承担教学责任，也不必从零开始；它应该围绕用户要完成的事组织，而不是围绕产品按钮或功能清单组织。
参考资料提供稳定、准确、完整的技术事实。它像地图或规格表，描述 API、参数、限制、错误码、配置项等。好的参考资料应当中立、结构一致，并尽量映射被描述系统本身的结构。它不负责说服、教学或带用户完成任务，而是给正在工作的用户一个可信的事实底座。
解释说明则回答“为什么”和“这意味着什么”。它提供背景、历史、取舍、设计理由和更大的图景，允许观点和比较，也允许从不同角度展开讨论。它不直接指导行动，却能让用户把零散知识编织成理解。Diátaxis 还用一张二维地图说明四者关系：一条轴区分行动与认知，另一条轴区分学习与工作。教程是“学习中的行动”，操作指南是“工作中的行动”，参考资料是“工作中的认知”，解释说明是“学习中的认知”。
深度解读
Diátaxis 的价值不在于发明了四个新栏目名，而在于它给文档团队提供了一套判断力。很多糟糕文档的问题，并不是写得不够多，而是类型混淆：教程里塞满概念论文，操作指南中途变成 API 参考，参考资料夹带主观解释，解释文章又突然给出半截步骤。用户的注意力被不断打断，作者也不知道自己该用什么语气写。Diátaxis 通过“这篇内容到底服务哪种需求”这个问题，迫使团队先明确意图，再决定写法、标题、结构和链接。
从 HN 讨论看，实践者对它的评价也很典型：有人在交接复杂代码库时发现，分类之后每一页该说什么、用什么声音说，都清晰了；也有人提醒不要把它当教条，重点不是把站点机械切成四个文件夹，而是确保每一块内容有明确类型。还有评论提到，在使用大模型生成文档时，“按 Diátaxis 来写”已经成为一种有效提示词，因为它能约束模型输出的目标、语气与边界。这说明 Diátaxis 正在从文档理论变成工程协作中的实用语言。
启示与展望
对技术团队来说，Diátaxis 最直接的启发是：文档治理应从“补齐内容”转向“匹配场景”。写新文档前，先判断读者是在学习、工作、查证还是理解；改旧文档时，也可以只做一个很小的改进，比如把解释挪出教程，把参数表从操作指南中抽成参考页。它不要求一次性重构全站，而鼓励持续整理。
未来，随着 AI 编程和自动化文档生成普及，文档数量会越来越多，结构和意图反而更稀缺。Diátaxis 这样的框架可能成为人类编辑与机器生成之间的共同协议：机器负责初稿和覆盖面，人类负责判断用户需求、信息边界和知识架构。真正优秀的文档，不只是“写得清楚”，而是让用户在正确的时刻遇到正确类型的帮助。