Diátaxis：系统化文档创作方法

引言

Diátaxis 是一种系统化的技术文档创作方法，旨在帮助写作者和团队更高效地思考、创建和组织技术文档。它由四个核心文档类型组成，分别对应文档用户的不同需求。该方法轻量、易学、无实现约束，已被数百个文档项目采纳，包括 Vonage、Gatsby 和 Cloudflare 等知名公司。

四种文档类型

Diátaxis 识别出用户使用文档时的四种基本需求，每种需求对应一种文档类型：

• 教程（Tutorials）：面向学习的用户，提供循序渐进的教学步骤，帮助用户获得第一手经验。
• 操作指南（How-to guides）：面向需要完成特定任务的用户，提供具体、可重复的操作步骤。
• 技术参考（Technical reference）：面向需要精确信息的用户，如 API 文档、配置说明等，强调准确性和完整性。
• 解释（Explanation）：面向需要理解深层原理的用户，提供背景知识、设计决策和概念讨论。

这四种文档类型并非孤立存在，而是相互关联、互为补充。Diátaxis 将它们置于一个系统化的关系中，并建议文档整体应围绕这些需求结构来组织。

应用价值

Diátaxis 不仅服务于文档用户，对文档创建者和维护者也有重要价值：

• 解决内容问题：明确“该写什么”以及“不该写什么”。
• 解决风格问题：指导如何根据文档类型选择合适的写作风格。
• 解决架构问题：帮助设计文档的目录结构和导航方式。

该方法还引入了一个主动的质量原则，帮助维护者有效反思自己的工作，持续改进文档质量。

实际案例

多家知名公司在其文档项目中成功应用了 Diátaxis：

• Vonage：内部文档团队借助 Diátaxis 构建了用户喜爱的高质量文档集。
• Gatsby：在重构开源文档时，Diátaxis 的四个象限帮助团队优先考虑用户目标，使文档更容易发现所需资源。
• Cloudflare：重新设计开发者文档时，Diátaxis 成为信息架构的北极星，让内容和贡献者都更加清晰。

理论原理

Diátaxis 的深层原理建立在用户需求分析之上。它包含：

• 基础（Foundations）：对文档用户需求的系统性理解。
• 地图（The map）：四种文档类型在一个二维空间中的关系图（教程 vs 操作指南、参考 vs 解释）。
• 质量（Quality）：如何评估文档是否满足用户需求。
• 工作流（Workflow）：基于 Diátaxis 的文档创作和维护流程。

此外，还探讨了复杂层级结构下的文档组织策略，以及如何在不同规模的项目中应用该方法。

总结

Diátaxis 提供了一种实用、系统的技术文档方法，帮助团队从用户需求出发，合理选择文档形式，优化内容与架构。它已被证明能有效提升文档的可用性和维护性，是技术写作领域的重要参考框架。

原标题：Diátaxis。 HN 原始发布时间：2026年8月2日星期日。当前记录为 529 分、58 条评论。

阅读原文 · 查看 HN 讨论