现代人几乎都会接触各种类型的技术文档：从消费电子产品的使用说明书，到软件工具的帮助中心；从云计算、AI 平台的开发者文档，到硬件设备、金融科技、医疗设备、工业系统、网络安全产品的技术规范与操作手册。
对普通用户来说，真正的痛点往往不是“没有文档”，而是文档太多、太散、太难判断该从哪里开始看。用户原本只是想完成一个具体任务：配置一个功能、排查一个报错、接入一个接口、导出一份报告，或者确认某个参数是什么意思，但现实中的技术文档常常把入门教程、操作步骤、参数说明、底层原理、版本差异和故障排查混在一起。结果是，新手被大量术语和前置知识劝退，熟练用户难以快速查到关键信息，非技术用户则缺少“我现在在哪一步、下一步该做什么、怎样才算成功”的路径感。技术文档本应降低使用门槛，却常常因为组织方式混乱，变成了用户理解产品、使用产品的第一道障碍。
可以说：好的技术文档是好的产品重要组成。有没有好的技术文档写作框架可以参考呢？
Diátaxis 是由 Ubuntu 前文档总监 Daniele Procida 提出的一个技术文档写作与组织框架，Diátaxis 来自古希腊语 δῐᾰ́τᾰξῐς，意思是““安排、布置”。
Diátaxis 认为各种技术文档难读的根源往往在于混淆了四种不同的用户需求。用户有时想“学”、有时想“做”、有时想“查”、有时想“懂”。如果一篇文档试图同时满足所有需求，就会变得臃肿、模糊，让用户和撰写者都沮丧痛苦。
Diátaxis ：https://diataxis.fr
Diátaxis 最核心的理念其实很简单：用户在阅读文档时，实际上有四种不同需求。不同的需求对应四种不同文档类型：Tutorials 教程、How-to guides 操作指南、Reference 参考文档、Explanation 解释性文档。
Diátaxis 的写作方法论
Diátaxis 的方法论建立在两个维度上：
- 行动 vs 认知：内容是告诉用户”做什么”，还是告诉用户”知道什么”
- 学习 vs 工作：用户当前处在”获取技能”的状态，还是”应用技能”的状态
把这两个维度交叉，就得到了 Diátaxis 的”坐标系地图”。
这套坐标系最有用的地方在于给了技术文档内容写作类型一个明确的判断工具：
- 如果一段内容指向”行动”且服务”学习”，属于教程 (Tutorials)。
- 如果一段内容指向”行动”且服务”工作”，属于操作指南 (How-to guides)。
- 如果一段内容指向”认知”且服务”工作”，属于参考文档 (Reference)。
- 如果一段内容指向”认知”且服务”学习”，属于解释说明 (Explanation)。
教程 (Tutorials) —— 面向学习 (Learning-oriented)
目标： 让初学者从零开始，成功完成一个基础项目。
特点： 像一位耐心的老师，手把手带你体验。这里不需要解释复杂的原理，重点是建立用户的信心。
例子： 教一个从来没有下过厨房的完全新手“第一次自己做番茄鸡蛋面”。从“先准备好所有食材和锅碗瓢盆”开始，每一步都手把手教（包括“水开了要放面条哦”“酱油要少放一点不然会咸”），最后能端出一碗完整的面条，让新手感受到“我居然真的做出来了”的成就感。
操作指南 (How-to guides) —— 面向目标 (Goal-oriented)
目标： 帮助有一定基础的用户解决特定的问题或完成具体任务。
特点： 像一本菜谱。它假设用户已经知道自己在做什么，只需要一系列可执行的步骤。
例子： 已经会做基本家常菜的人想知道“如何快速做一顿工作日10分钟晚餐的番茄鸡蛋面”。直接列出“1. 水烧开下面条 2. 同时热锅炒鸡蛋 3. 加番茄和调料翻炒 4. 面条煮好后捞出拌匀”，直奔主题，假设你已经知道怎么开火、怎么切菜。
参考文档 (Reference) —— 面向信息 (Information-oriented)
目标： 提供准确、详尽的技术细节。
特点： 像一本字典或百科全书。它不教你如何使用，只告诉你“它是什么”。内容应该严谨、全面、没有废话。
例子： 厨房墙上贴的“常用厨房度量换算表”、“常见食物卡路里与营养成分对照表”
解释说明 (Explanation) —— 面向理解 (Understanding-oriented)
目标： 阐述系统背后的设计理念、架构和历史背景。
特点： 像一篇深度的技术专栏。帮助读者建立宏观认知，解答“为什么这么设计”的疑惑。
例子： 一篇题为《为什么番茄炒鸡蛋加糖会更好吃？》的文章。解释番茄里的酸味、鸡蛋的鲜味、糖如何中和酸味并提升整体风味，还可以聊聊中式烹饪里“甜咸平衡”的传统原理，帮助你真正理解这道菜背后的“为什么”，而不是教你怎么炒。
落地实践
The Good Docs Project 是一个基于 Diátaxis 分类法的开源项目，提供各种文档模板，包括Tutorial、How-to、Reference、Concept、Release Notes 等。
The Good Docs Project：https://www.thegooddocsproject.dev/
其他技术类文档“结构化写作”方法论
技术类文档的写作还有很多知名的”结构化写作”，包括：
DITA（Darwin Information Typing Architecture）
2001 年由 IBM 提出、2004 年捐给 OASIS 维护，是企业文档圈用得最广的一套标准。DITA 的核心是把内容按类型拆分，主要分三类：concept（概念）、task（任务）、reference（参考）。
Information Mapping
1960 年代由 Robert Horn 提出。核心主张是把内容拆成”信息块（information block）”，每块只包含一种信息类型（程序、概念、事实、原则、流程、结构、分类）。
Information Mapping 主要被用在政策文档、SOP、合规手册、企业培训材料领域。
Every Page Is Page One
来自 Mark Baker 的同名书。核心主张：强调现代用户通常不是从文档首页线性阅读，而是通过搜索引擎、站内搜索、链接、AI 摘要直接进入某个页面，因此每个页面都应该尽量能独立成立。
这也是目前流行的单页设计的思想来源。
还有Topic-based Writing、README-driven development、API-first / OpenAPI 文档方法、Docs as Code等形形色色的技术写作方法，就不一一列举了。