按 Diátaxis 创建…

当你需要编写、重构或审查技术文档，并根据用户是学习、解决问题、查询事实还是理解概念来选择合适文档类型时使用。

适用场景

解决思路

1. 将技术文档组织成四种不同类型：教程（tutorials）、操作指南（how-to guides）、参考资料（reference material）、解释（explanations），每类服务不同用户需求与上下文。
2. 在创建文档之前，先向用户询问其上下文、受众和目标。
3. 根据用户信号判断文档类型：用户说“我是 X 的新手，想学习它”/“带我一步步做” → 教程（Tutorial）。
4. 根据用户信号判断文档类型：用户说“我如何…？”/“我需要完成 X” → 操作指南（How-to guide）。
5. 根据用户信号判断文档类型：用户问“X 的参数/选项/语法是什么？” → 参考资料（Reference）。
6. 根据用户信号判断文档类型：用户问“X 为什么这样工作？”/“帮我理解 X” → 解释（Explanation）。
7. 用快速决策树判断：用户是否第一次边做边学？ → 教程。
8. 用快速决策树判断：用户是否需要解决一个他已经理解的具体问题？ → 操作指南。
9. 用快速决策树判断：用户是否需要查找技术事实？ → 参考资料。
10. 用快速决策树判断：用户是否需要概念背景？ → 解释。
11. 教程（学习导向）标题模式：以动词开头，如 “Build your first X”、“Create a Y from scratch”。
12. 教程结构：目标 → 前置条件 → 编号步骤 → 每一步都有即时可验证结果 → 最终结果。
13. 教程中尽量减少解释，最大化动手操作。
14. 教程每一步都必须产生可见、可测试的结果。
15. 教程验证：初学者必须能在没有外部帮助的情况下完成教程。
16. 教程示例引言可写成：“在本教程中，你将使用 Express 构建一个简单的 REST API。到结束时，你将有一个能响应 GET 请求的运行中服务器。不需要预先具备 Express 经验。”
17. 操作指南（问题导向）标题模式：按任务表述，如 “How to configure X”、“How to deploy Y to Z”。
18. 操作指南结构：目标声明 → 假设/前置条件 → 编号步骤 → 预期结果。
19. 操作指南假设用户已有基础知识；跳过概念解释。
20. 操作指南允许变化；在存在替代方案时注明替代方案。
21. 操作指南验证：有经验的用户能完成任务而不困惑、不反复回退。
22. 操作指南示例引言可写成：“本指南展示如何向现有 Express 应用添加 JWT 认证。它假设你已有可工作的 Express 服务器，并基本熟悉 middleware。”
23. 参考资料（信息导向）标题模式：命名事物，如 “Configuration options”、“API endpoints”、“CLI flags”。
24. 参考资料结构：每个条目使用一致可重复的格式（name → type → default → description → example）。
25. 参考资料陈述事实；除最小使用示例外避免指令。
26. 参考资料保持最新；如有需要标注版本。
27. 参考资料验证：用户能在 30 秒内查找到特定事实，而无需阅读周围内容。
28. 参考资料示例条目可写成：**`timeout`**（integer，默认值：`5000`）请求失败前等待响应的最大毫秒数。示例：`{ timeout: 3000 }`
29. 解释（理解导向）标题模式：按概念表述，如 “How X works”、“Understanding Y”、“Why Z is designed this way”。
30. 解释结构：上下文 → 核心概念 → 替代方案/权衡 → 更高层视角。
31. 解释避免逐步指令或技术规格。
32. 解释验证：读完后，用户能用自己的话解释概念，并理解决策背后的理由。
33. 解释示例引言可写成：“认证（authentication）和授权（authorisation）经常被混淆。本页解释二者的区别、为什么都重要，以及常见模式（sessions、tokens、OAuth）如何以不同方式处理各自关注点。”
34. 保持分离与整合：每篇文档只保留一种类型——不要把教程步骤与参考表格或概念离题混在一起。
35. 在不同类型之间交叉链接：教程可以链接到相关参考页；操作指南可以链接到解释页作为背景。
36. 在所有类型中使用一致的标题和术语，以便用户在完整文档系统中导航。
37. 交付前验证——教程：初学者能否在没有外部帮助的情况下端到端完成？
38. 交付前验证——操作指南：是否能替有经验的用户解决所述问题？
39. 交付前验证——参考资料：用户能否在 30 秒内找到特定事实？
40. 交付前验证——解释：用户是否理解 why，而不只是 what？

适用边界 · 注意事项

• 不适用于非技术文档，例如营销文案、法律条款、纯观点文章。
• 当文档只是极小的一次性说明，且没有按用户需求拆分或长期维护导航的需要时，不必强行套用四类结构。
• 当用户明确要求在同一份文档中混合教程、参考和解释，且不关心后续维护/导航时，严格的类型分离可能不适用。