Explanation 类型文档写作规范
定义
Explanation 是理解导向的文档，帮助读者理解概念、原理和背景，回答"为什么"的问题。
核心特征
| 特征 | 要求 | 对比其他类型 |
|---|---|---|
| 目的 | 建立理解和认知 | Reference: 提供查询 How-to: 解决问题 Tutorial: 教授技能 |
| 阅读方式 | 顺序阅读，逐步深入 | Reference: 跳跃查找 How-to: 按需阅读 Tutorial: 跟随练习 |
| 内容组织 | 自然叙述，逻辑递进 | Reference: 高度结构化 How-to: 任务步骤 Tutorial: 学习路径 |
| 语言风格 | 通俗易懂，可以口语化 | Reference: 技术精确 How-to: 简洁指令 Tutorial: 友好引导 |
| 前置知识 | 假设读者不了解 | Reference: 假设已了解 How-to: 假设有背景 Tutorial: 零基础 |
适用场景
应该写 Explanation
- 概念介绍和原理解释
- 设计理念和思想阐述
- 架构决策和权衡说明
- 历史背景和演进过程
- 理论基础和方法论
不该写 Explanation
- 具体操作步骤 → How-to
- 参数配置说明 → Reference
- 学习练习教程 → Tutorial
- 纯技术规格 → Reference
必要元素
| 元素 | 说明 | 必需性 |
|---|---|---|
| 主题定义 | 一句话说清是什么 | 必需 |
| 背景动机 | 为什么需要关心这个 | 必需 |
| 核心概念 | 关键概念和原理 | 必需 |
| 具体示例 | 用例子加深理解 | 必需 |
| 价值意义 | 对读者的实际价值 | 必需 |
| 引用来源 | 理论依据和参考资料 | 必需 |
| 核心思想 | 背后的哲学理念 | Pattern层必需 |
质量标准
必须满足
- [ ] 开篇100字内说清主题
- [ ] 至少包含一个具体例子
- [ ] 明确说明实际价值
- [ ] 语言通俗无学术腔
- [ ] 提供可操作的下一步
- [ ] 包含必要的引用
- [ ] 文风自然流畅
必须避免
- [ ] 长篇理论铺垫
- [ ] 纯技术细节罗列
- [ ] 机械的模板结构
- [ ] 过度使用术语
- [ ] 缺乏具体例子
- [ ] 没有实际价值
- [ ] 虚假的例子（详见下方说明）
文风要求
语言原则
- 通俗化 - 用日常语言替代专业术语
- 具象化 - 用类比和例子替代抽象概念
- 自然化 - 用流畅叙述替代条目罗列
- 个性化 - 保持作者声音，避免千篇一律
避免AI味
- 不使用机械的章节标记（【开篇】【动机】等）
- 不过度使用bullet points
- 不用生硬的"核心目的"、"内容要求"等标签
- 段落之间自然过渡，不要机械分割
组织建议
逻辑流程
- 引入 - 快速建立认知
- 展开 - 逐步深入解释
- 例证 - 用实例强化理解
- 总结 - 强调核心价值
灵活处理
- 根据内容调整章节
- 可以融合多个元素
- 标题应该有信息量
- 保持叙述的连贯性
写作技巧
| 技巧 | 说明 | 示例 |
|---|---|---|
| 类比法 | 用熟悉事物解释陌生概念 | 文档体系像四层楼房子 |
| 对比法 | 通过对比突出特点 | 以前...现在... |
| 问答法 | 预设疑问并解答 | "你可能会问..." |
| 故事法 | 用叙事引入概念 | "想象这样一个场景..." |
关于例子的使用
虚拟 vs 虚假：
✅ 虚拟（可以）：想象的场景，但合理真实
- "想象你要学开车..."
- "假设有一个电商网站..."
- "如果你正在开发一个新功能..."
❌ 虚假（避免）：假装发生过的事实
- "去年我们整理文档时..." （除非真的发生过）
- "经过三个月的实践..." （除非真有数据）
- "用户反馈显示..." （除非真有反馈）
原则：可以创造场景帮助理解，但不要编造事实误导读者。
层级特殊要求
Pattern 层 Explanation
- 必须包含"核心思想"或"设计哲学"部分
- 阐述理念来源和价值观
- 说明思维模式的转变
- 解释与传统方式的本质区别
其他层级
- Protocol 层：重点解释标准制定的原因
- Practice 层：重点解释方案选择的理由
- Products 层：重点解释实现决策的考虑
检查清单
完成后验证：
- 理解测试 - 新手3分钟能理解核心概念吗？
- 价值测试 - 读者知道为什么要关心吗？
- 记忆测试 - 读者能记住关键点吗？
- 流畅测试 - 大声朗读是否自然？
- 实用测试 - 读者知道下一步做什么吗？
与其他类型的关系
| 关系类型 | 说明 |
|---|---|
| 补充 Reference | Explanation 解释原理，Reference 提供详细规格 |
| 引导 How-to | Explanation 说明为什么，How-to 说明怎么做 |
| 深化 Tutorial | Tutorial 教基础操作，Explanation 解释深层原理 |
维护原则
- 定期更新概念和理论
- 根据反馈优化表达
- 补充新的例子和类比
- 保持与其他文档的一致性
参考资源
- Diátaxis - Explanation - Diátaxis 框架对 Explanation 的定义
- 理解Deepractice内容体系 - Explanation 实践示例
- 文件命名规范 - 文档文件命名标准
记住：Explanation 不是在"解释"，而是在"让人理解"。