1. Diátaxis – A systematic approach to technical documentation authoring (diataxis.fr)
Diátaxis:技术文档编写系统方法
Diátaxis 是一种用于理解和执行技术文档工作的系统性思维方法。它从系统性地理解文档用户需求出发,为文档的内容、架构和形式提供了指导方针。
核心概念与结构
Diátaxis 识别了用户的四种根本需求,并相应定义了四种文档形式:
- 教程 (Tutorials):面向学习,是教学性质的课程。
- 操作指南 (How-to guides):面向解决问题,是完成特定任务的步骤。
- 技术参考 (Technical reference):面向信息查询,是技术描述。
- 解释 (Explanation):面向理解,是讨论或阐述。
这四种形式并非孤立,Diátaxis 将它们置于一个系统性的关系中,并主张文档的组织结构应围绕这些需求进行构建。
解决的问题与优势
该方法解决了文档工作中的几个关键问题:
- 内容:明确知道该写什么。
- 风格:知道如何撰写不同类型的内容。
- 架构:知道如何组织文档。
它不仅有利于文档使用者,对文档创建者和维护者同样有价值。Diátaxis 轻量、易于理解且便于应用,不强制实施约束,并引入了一个有效的质量原则,能帮助维护者深入思考其工作。
实践验证与应用
Diátaxis 已在实践中得到验证,其原则已被数百个文档项目成功采用。多个行业案例证明了其有效性:
- Vonage:用于构建了一套用户喜爱的高质量内部文档。
- Gatsby:在重组其开源文档时,Diátaxis 框架是首选参考,其四象限结构帮助优先考虑了每类文档的用户目标,使用户能更轻松地发现所需资源。
- Cloudflare:在重新设计开发者文档时,Diátaxis 成为信息架构的指导原则,帮助确定了新内容的位置,最终使文档对读者和贡献者都更加清晰。