写技术文档，不只是填模板 —— 从共情视角做有用的系统设计文档-优快云博客

本文链接：https://blog.youkuaiyun.com/hemoparrot/article/details/147054710

🚀“为什么文档没人看？” “为什么写文档这么痛苦？” “为什么交了文档，开发还是一团乱？”

这些问题，几乎每个技术人都经历过。

我们经常这样写文档：

找个旧模板改改标题，快速填完交差；
把架构图、接口说明、流程图统统堆进去；
写完发出去，却发现没人看、没人用；

其实问题并不在你写得不够多，而是你写的内容对读者不重要。

这正是设计思维（Design Thinking）中最重要的一环：共情（Empathy）。

💡 什么是“共情式文档”？

📌 从“写给谁、解决什么问题”出发，而不是“我有啥内容就写啥”。

很多“为了写而写”的文档，看起来内容齐全，实际上无用信息一堆。

而共情式文档是一种“以用户为中心”的技术表达方式，它关注的是：

谁会看这份文档？
他/她在什么场景下会来看？
他/她最需要什么内容？

📚 用“共情视角”设计文档结构

以下是一个 BLE 模块开发项目中，不同类型文档、读者与内容的典型匹配：

📄 文档类型	👤 典型读者	📌 使用场景	🔍 核心内容
系统设计方案	架构师 / 开发者	方案评审 / 模块分工	模块职责 / 数据流 / 状态机
接口说明 / 开发手册	开发者	实现模块 / 使用接口	接口说明 / 参数 / 示例调用
需求实现对照表	测试 / 产品	功能验收 / 版本审查	需求功能 / 实现接口 / 状态
项目总览 / 快速上手	新人 / 管理层	快速了解项目 / 分配任务	架构图 / 模块边界 / 编译运行
技术选型记录	架构师 / 评审人	回顾决策 / 评估替代方案	选型比较 / 选用理由 / 风险项

📌 每类文档都应该“聚焦一个角色 + 一个使用场景”，不要混写！

🧭 共情式文档的三大原则

✅ 1. 谁在什么场景下需要看？

是在调试现场查接口用法的开发？
是刚接手项目、不知道从哪开始的新同事？
是测试阶段急着找到需求对应点的 QA？

想清楚读者是谁，就知道“写多少、怎么写、写在哪”。

✅ 2. 他最关心什么？

是“调用顺序怎么写”？
是“状态切换条件是什么”？
是“需求是不是都落地了”？

写文档 ≠ 把脑子里的东西倒出来，而是：

把对方脑子里找不到的东西，清晰地提供出来。

✅ 3. 能不能一眼找到？

📑 加目录（TOC）让他不用 Ctrl+F
🧱 用表格和图解替代纯文字说明
💡 高频问题单独列出 FAQ 区块

写技术文档不是写小说，要让读者“秒定位”。

📌 案例对比：FSM 状态机模块

❌ 常见错误写法（为写而写）

3. 状态枚举定义如下：
typedef enum {
  BLE_INIT, BLE_ADV, BLE_SCAN, BLE_CONN
} ble_state_t;

✅ 共情写法（讲清楚怎么用）

## 3. FSM 状态机模块说明

### 🔁 状态概览
| 状态 | 描述     | 广播 | 扫描 | 连接 |
|------|----------|------|------|------|
| INIT | 初始状态 | ❌   | ❌   | ❌   |
| ADV  | 广播中   | ✅   | ❌   | ❌   |

### 🔀 状态切换触发表
| 当前状态 | 事件 / 命令      | 目标状态 | 说明               |
|----------|------------------|----------|--------------------|
| INIT     | `AT+BLEINIT`     | ADV      | 初始化后进入广播   |
| ADV      | BLE_CONNECTED    | CONN     | 被手机连接成功     |

### 💡 使用示例
```c
fsm_handle_event(BLE_EVENT_CONNECTED);