why-what-how

name	why-what-how
description	确保技术文档符合 Why-What-How 三段式结构，但用自然的标题呈现（问题-目标-方案）。检查文档逻辑是否完整，不符合则修改。当生成或审查 README、设计文档、技术方案、功能说明时使用。

Why-What-How 文档结构

技术文档应该让读者快速明白：有什么问题、要达成什么、怎么做到。

但别把 "Why"、"What"、"How" 直接写成标题——这太模板化了。

逻辑结构与自然表达

内在逻辑用自然的标题呈现：

逻辑	自然标题选择
Why	问题、背景、现状、痛点、动机
What	目标、方案概述、核心思路、做什么
How	解决方案、实现、技术方案、使用方法、操作步骤

选择哪个标题，看上下文和文档类型。

检查流程

审查文档时，检查这三层逻辑是否存在（不管标题叫什么）：

1. 找 Why（问题层）

文档前 1-2 段应该回答：

• 现状是什么？
• 哪里不好？
• 为什么要改变？

缺失信号：开头直接讲功能或方案，没说为什么要做。

2. 找 What（目标层）

应该包含：

• 要达到什么效果
• 核心能力/功能
• 边界在哪（做什么、不做什么）

缺失信号：只讲怎么做，没说要做成什么样。

3. 找 How（方案层）

应该包含：

• 具体方案/步骤
• 使用方法或实现细节

缺失信号：只有概念没有落地，或步骤不完整。

修改策略

Why 缺失

在文档开头补充问题描述。不要写"背景"然后列一堆条目，直接说：

## 问题

目前 [现状]，导致 [痛点]。

或融入开头段落：

# Config Sync

配置散落在多处，部署时手动同步容易漏。这个工具自动检测和同步配置变更。

What 缺失

在问题之后、方案之前补充目标：

## 目标

- [要达成的效果 1]
- [要达成的效果 2]

或写成段落：

做一个配置同步工具，能自动发现配置变更并同步到所有环境。

How 缺失

根据文档类型补充：

• README：快速开始、安装、基本用法
• 设计文档：技术方案、架构、接口
• 功能说明：操作步骤、配置示例

正反例

同一个项目，两种写法：

反例

# Data Sync

## What
一个数据同步工具。

## How
npm install data-sync

问题：不知道解决什么；标题像套模板。

正例

# Data Sync

多数据源场景下，手动同步容易遗漏，出问题难排查。

## 目标

- 自动同步数据库间的数据变更
- 增量传输，只同步差异
- 冲突时能检测并提示

## 快速开始

npm install -g data-sync

区别：

• Why 融在开头，不单独加标题
• What 用"目标"而非"What"
• How 用"快速开始"而非"How"

不同文档的标题选择

文档类型	Why 可用标题	What 可用标题	How 可用标题
README	开头段落（不加标题）	功能、特性	快速开始、安装、使用
设计文档	问题、背景	目标、方案概述	技术方案、详细设计
RFC/提案	动机、问题	提案内容、目标	实现方案
功能说明	为什么做这个	功能说明	如何使用、操作指引

检查清单

• 能找到问题/动机吗？（Why 逻辑存在）
• 能找到目标/定义吗？（What 逻辑存在）
• 能找到方案/步骤吗？（How 逻辑存在）
• 顺序对吗？（先问题，再目标，最后方案）
• 标题自然吗？（没有直接写 Why/What/How）