Why-What-How 文档结构
技术文档应该让读者快速明白：有什么问题、要达成什么、怎么做到。
但别把 "Why"、"What"、"How" 直接写成标题——这太模板化了。
逻辑结构与自然表达
内在逻辑用自然的标题呈现：
| 逻辑 | 自然标题选择 |
|---|---|
| Why | 问题、背景、现状、痛点、动机 |
| What | 目标、方案概述、核心思路、做什么 |
| How | 解决方案、实现、技术方案、使用方法、操作步骤 |
选择哪个标题，看上下文和文档类型。
检查流程
审查文档时，检查这三层逻辑是否存在（不管标题叫什么）：
1. 找 Why（问题层）
文档前 1-2 段应该回答：
- •现状是什么？
- •哪里不好？
- •为什么要改变？
缺失信号：开头直接讲功能或方案，没说为什么要做。
2. 找 What（目标层）
应该包含：
- •要达到什么效果
- •核心能力/功能
- •边界在哪（做什么、不做什么）
缺失信号：只讲怎么做，没说要做成什么样。
3. 找 How（方案层）
应该包含：
- •具体方案/步骤
- •使用方法或实现细节
缺失信号：只有概念没有落地，或步骤不完整。
修改策略
Why 缺失
在文档开头补充问题描述。不要写"背景"然后列一堆条目，直接说：
markdown
## 问题 目前 [现状]，导致 [痛点]。
或融入开头段落：
markdown
# Config Sync 配置散落在多处，部署时手动同步容易漏。这个工具自动检测和同步配置变更。
What 缺失
在问题之后、方案之前补充目标：
markdown
## 目标 - [要达成的效果 1] - [要达成的效果 2]
或写成段落：
markdown
做一个配置同步工具，能自动发现配置变更并同步到所有环境。
How 缺失
根据文档类型补充：
- •README：快速开始、安装、基本用法
- •设计文档：技术方案、架构、接口
- •功能说明：操作步骤、配置示例
正反例
同一个项目，两种写法：
反例
markdown
# Data Sync ## What 一个数据同步工具。 ## How npm install data-sync
问题：不知道解决什么；标题像套模板。
正例
markdown
# Data Sync 多数据源场景下，手动同步容易遗漏，出问题难排查。 ## 目标 - 自动同步数据库间的数据变更 - 增量传输，只同步差异 - 冲突时能检测并提示 ## 快速开始 npm install -g data-sync
区别：
- •Why 融在开头，不单独加标题
- •What 用"目标"而非"What"
- •How 用"快速开始"而非"How"
不同文档的标题选择
| 文档类型 | Why 可用标题 | What 可用标题 | How 可用标题 |
|---|---|---|---|
| README | 开头段落（不加标题） | 功能、特性 | 快速开始、安装、使用 |
| 设计文档 | 问题、背景 | 目标、方案概述 | 技术方案、详细设计 |
| RFC/提案 | 动机、问题 | 提案内容、目标 | 实现方案 |
| 功能说明 | 为什么做这个 | 功能说明 | 如何使用、操作指引 |
检查清单
- • 能找到问题/动机吗？（Why 逻辑存在）
- • 能找到目标/定义吗？（What 逻辑存在）
- • 能找到方案/步骤吗？（How 逻辑存在）
- • 顺序对吗？（先问题，再目标，最后方案）
- • 标题自然吗？（没有直接写 Why/What/How）