WISE 技术文档结构: 结论先行与渐进展开
# WISE 技术文档结构: 结论先行与渐进展开
## 1. 结论
技术文档默认采用 WISE 结构:
1
2
3
4
5
6
7
8
9
10
11
W — What
结论 / 具体做法
↓
I — Insight
简要说明原因
↓
S — System
进一步解释核心机制与边界
↓
E — Evidence
引用文献 / 理论来源 / 延伸阅读
目标不是让所有读者完整阅读全文, 而是允许读者根据自己的需求随时停止:
1
2
3
4
5
6
7
8
9
10
11
只需要解决问题
→ 阅读 What
需要知道为什么
→ 阅读 What + Insight
需要真正理解机制
→ 阅读 What + Insight + System
需要系统学习或验证来源
→ 阅读完整 WISE
因此, 技术文档不采用“先铺背景, 最后给结论”的默认结构.
## 2. 为什么采用这种结构
工程文档通常承担两种不同职责:
1
2
3
查阅
+
学习
查阅者往往已经知道问题是什么, 只需要快速找到:
1
2
3
应该怎么做?
应该怎么判断?
应该使用什么方案?
而学习者还希望继续了解:
1
2
3
4
为什么?
内部机制是什么?
什么情况下不成立?
有没有更系统的理论来源?
如果从背景开始逐层推导, 第二类读者可以获得完整信息, 但第一类读者必须阅读大量当前并不需要的内容.
因此更合理的组织方式是:
先提供足以行动的信息, 再逐步提供理解这些信息所需的上下文.
Microsoft Style Guide 对技术内容也采用类似原则, 强调将最重要的信息放在前面, 并通过标题、列表和短段落提高内容的可扫描性.
## 3. WISE 四个层级分别解决什么问题
### W — What
首先回答:
1
2
3
应该做什么?
推荐什么方案?
如何判断?
这一部分应该可以脱离后文独立使用.
例如:
对持续影响 Frame Budget 的大型任务, 可以评估分帧处理. 但在采用分帧之前, 必须同时设计中间状态、任务失效、结果提交和资源清理机制.
读者看到这里已经能够做出基本的工程判断.
### I — Insight
解释为什么得到这个结论.
例如:
1
2
3
4
分帧
→ 降低单帧峰值
→ 但任务跨越多个 Frame
→ 系统因此出现中间状态
这一层只建立主要因果关系, 不展开所有细节.
### S — System
继续解释:
1
2
3
4
5
中间状态为什么危险?
输入变化以后怎么办?
为什么需要 Snapshot?
为什么需要 Commit / Swap?
什么任务不适合分帧?
这一层用于把“工程经验”进一步变成可以迁移到其他问题上的理解.
除了内部机制, 这里还应讨论真正影响工程决策的:
1
2
3
4
边界条件
失败路径
例外情况
适用范围
### E — Evidence
最后提供:
1
2
3
4
5
原始论文
官方文档
经典文章
实验数据
相关理论
用于回答:
1
2
3
这个观点从哪里来?
有没有更完整的理论体系?
我还可以继续学习什么?
正文不依赖读者阅读这些资料才能使用, 但希望深入的人可以继续追溯.
## 4. 核心思想: Progressive Depth
可以把 WISE 理解为一种信息深度的逐级增加:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Level 1
What
结论 / 做法
Level 2
Insight
主要原因
Level 3
System
机制 / 边界
Level 4
Evidence
理论 / 证据
每增加一级, 信息量增加, 但前一级仍然保持完整.
这与交互设计中的 Progressive Disclosure, 即“渐进式披露”有相似思想: 先暴露最重要的信息, 高级和低频信息在用户需要时再进一步展开. Nielsen Norman Group 将这种方法用于降低复杂界面的认知负担; 在文档中可以采用类似的信息组织思想.
它也与技术写作中的 Inverted Pyramid, 即“倒金字塔结构”相近: 先给最重要的结论, 后面再逐渐补充细节. 相关技术写作资料也明确建议技术报告首先给出主要结论.
但 WISE 不是对某一种既有方法的直接复制, 而是针对工程技术文档整理出的使用约定.
## 5. 实际写作原则
采用 WISE 时, 还需要遵守几个原则:
1
2
3
4
5
1. What 必须可以独立使用.
2. Insight 不重复 What, 而是解释主要因果关系.
3. System 讨论真正影响工程决策的机制、边界和例外.
4. Evidence 用于追溯和深入, 不替代正文解释.
5. 后面的内容不能推翻前面的结论, 只能增加条件和精度.
如果一个结论存在重要前提, 前提必须在 What 或 Insight 中出现, 不能把关键限制隐藏到文档后面.
例如不能写成:
1
2
3
4
5
6
7
What:
推荐使用分帧.
...
System:
实际上这个系统不允许出现中间状态.
而应该从一开始写成:
1
2
What:
可以考虑分帧, 但前提是系统能够安全管理未完成状态.
否则所谓“结论先行”, 实际上只是提前给出了一个不完整的结论.
## 6. 最终目标
WISE 追求的不是“越短越好”, 也不是“越完整越好”.
目标是:
让不同深度需求的读者, 都只阅读完成当前任务所需要的最少内容.
因此完整文档仍然可以包含充分的机制解释、边界讨论和理论资料, 但最重要的信息始终位于最前面.
一篇文档可以同时承担:
1
2
3
快速查阅
+
完整学习
而不需要分别维护“简略版”和“完整版”.
## 7. Evidence: 相关资料
WISE 本身是本文采用的工程文档组织约定, 不是某一篇文献提出的固定模型.
其设计可以参考以下几个相近思想:
### 7.1 Scannable Content
Microsoft Style Guide 强调重要信息前置, 并通过标题、列表、短段落等方式提高技术内容的可扫描性.
参考:
Microsoft Style Guide - Scannable content
### 7.2 Progressive Disclosure
Nielsen Norman Group 的 Progressive Disclosure 讨论如何首先提供重要和常用信息, 再根据需要逐步暴露更复杂的信息, 从而降低认知负担.
WISE 借鉴的是这种“按需求逐渐增加信息深度”的思想.
参考:
Nielsen Norman Group - Progressive Disclosure
### 7.3 Inverted Pyramid
Inverted Pyramid, 即“倒金字塔结构”, 强调把最重要的信息和结论放在前面, 再逐步补充依据、解释和细节.
这与 WISE 的 What First 原则直接对应.
参考:
University of Utah - Inverted Pyramid for Technical Writing
## 8. 总结
WISE 的完整结构是:
1
2
3
4
5
6
7
8
9
10
11
W — What
结论 / 具体做法
I — Insight
简要原因
S — System
核心机制 / 边界 / 例外
E — Evidence
理论 / 文献 / 数据 / 延伸阅读
其核心思想可以概括为:
结论先行, 按需深入.
读者首先获得足够用于判断和行动的信息. 如果需要进一步理解, 再依次进入原因、系统机制和理论依据.
因此, WISE 可以作为技术 Blog、工程说明和技术方案文档的默认组织结构.