技术写作之道指南

# 技术写作之道指南

文档结构设计、技术博客、方案撰写套路——写清楚比写得多重要

# 一、技术写作不是"写作文"，是"降低理解成本"

大多数工程师写文档时的心态：

"我懂了就行，随便写写。反正没人看。"

然后你的设计文档被后来的同事打开，读了 10 分钟还是不知道你在说什么——他只能跑来打断你，问 20 分钟。你为了省 20 分钟写文档的时间，未来要花 200 分钟回答问题。

技术写作的核心目标就一个：让读者用最短时间理解你想表达的东西。

❌ 写给自己看的 → 只有你自己能看懂，3 个月后你自己也看不懂
✅ 写给读者看的 → 任何有基本上下文的人都能看懂，不需要追问

1
2

# 二、技术文档的结构——两个铁律

# 2.1 TL;DR 前置

TL;DR（Too Long; Didn't Read）不是给懒人看的——是给需要你的文档但不需要全部细节的人看的。

技术方案文档的标准结构：

# 标题
> TL;DR：用 3 句话说明——要做什么、为什么现在做、核心方案是什么

## 1. 背景与问题        ← 不关心的人看完 TL;DR 就不用往下翻了
## 2. 方案对比
## 3. 详细设计
## 4. 风险与应对
## 5. 排期与分工

1
2
3
4
5
6
7
8
9
10

TL;DR 公式：

[做什么]，以解决 [什么问题]。
核心方案是 [一句话描述]，预计 [完成时间]。
关键决策：[最重要的技术选型/取舍]。

1
2
3

# 2.2 先说结论，再说过程

程序员最容易犯的写作错误：按时间顺序写，而不是按重要程度写。

❌ 按你的思考过程写：
"我们最开始想用 Redis 做缓存，但是发现内存不够，然后调研了 Memcached，
发现也不合适，后来看到一篇博客说可以用本地缓存 + 分布式锁……"
→ 读者在这段废话里找你到底用了什么方案。

✅ 按重要性写：
"最终方案：Caffeine 本地缓存 + Redis 分布式锁。
为什么不用纯 Redis：内存成本估算每月 ¥8000，不可接受。
备选方案对比表见下文。"
→ 读者第一句就知道结论了。

1
2
3
4
5
6
7
8
9
10

原则：任何段落的第一句话都应该能独立回答"这一段在说什么"。如果读者只读每段第一句，他应该能理解文档的 80%。

# 三、技术博客——你为什么要写

# 3.1 博客不是工作汇报

❌ "我们项目这周做了 A、B、C 三个功能。" ← 没人关心你的项目周报
✅ "做 A 功能时遇到一个死锁问题，排查过程是这样的……" ← 别人能学到东西

1
2

博客的读者不是你同事——他们不知道你的项目背景。你要给你的文章一个独立存在的意义：读者读完能带走什么？

三种有传播力的技术博客：

类型	例子	适合写的人
踩坑记录	"MySQL 8.0 升级后 time_zone 表导致连接失败的排查"	所有人
原理深挖	"从 epoll 到 io_uring——Linux IO 模型的演进"	对底层感兴趣的人
对比评测	"React Query vs SWR vs RTK Query——数据请求库选型"	做过技术选型的人

# 3.2 博客结构公式：STAR + Insight

S - Situation（背景）：我在什么项目/场景下遇到这个问题
T - Task（问题）：具体是什么问题，现象是什么
A - Action（过程）：怎么排查的，试过哪些方案
R - Result（结果）：最终怎么解决的，效果怎样
+ Insight（洞察）：做完之后有什么收获，能不能抽象成通用规律

1
2
3
4
5

STAR 让文章有骨架，Insight 让文章有价值。 没有 Insight 的踩坑记录就是流水账。

# 3.3 代码是最费读者的东西——省着用

❌ 贴一整段 50 行的代码，然后写："核心逻辑如上。"
→ 读者不知道重点在哪行。

✅ 贴 5-8 行关键代码，用注释标注关键行：
```java
// 关键：这里用了 CompletableFuture 的 thenCombine，
// 将两个独立的远程调用并行化，总耗时从 A+B 降到 max(A, B)
CompletableFuture&lt;User> userFuture = userService.getUserAsync(userId);
CompletableFuture&lt;Order> orderFuture = orderService.getOrderAsync(orderId);
userFuture.thenCombine(orderFuture, (user, order) -> {
    return new UserOrderResult(user, order);
});

1
2
3
4
5
6
7
8
9
10
11
12


代码片段旁边必须有注释解释**为什么这么写**——代码本身只能说明"怎么做的"，不能说明"为什么这么做"。

---

## 四、技术方案——让评审人快速说"同意"

### 4.1 方案评审的本质是"消除担心"

评审人看你的方案，不是在找亮点——是在找风险。你越快让他确认"没有坑"，他越快说同意。

一份好方案应该主动回答评审人脑子里的四个问题：

```text
问题 1：为什么要做？（有没有数据？还是拍脑袋？）
  → 回答：一张图/一个链接/一句引用。不要"我觉得"。

问题 2：为什么选这个方案？（对比过其他方案吗？）
  → 回答：一个对比表。3 列：方案名、优点、为什么不选。

问题 3：影响有多大？（下游谁会被影响到？）
  → 回答：一句话 + 一个影响清单。如果只改你自己的服务，直接说明。

问题 4：失败了怎么办？（有回滚方案吗？）
  → 回答：回滚步骤（能一行命令就别写一段话）+ 监控验证方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# 4.2 方案对比表——用一分钟取代一小时讨论

| 维度 | 方案 A：MQ 异步 | 方案 B：线程池 | 方案 C：不处理 |
|---|---|---|---|
| 可靠性 | 高（消息持久化） | 中（重启丢失） | N/A |
| 延迟 | +50ms（网络开销） | +5ms | 0 |
| 复杂度 | 引入新组件 | 纯代码 | 无 |
| 开发成本 | 2 天 | 0.5 天 | 0 |
| **结论** | **推荐** | 备选 | 不可接受 |

理由：当前 QPS 不高，但后续计划上大促，MQ 的削峰能力未来会需要。
一次性引入，避免 3 个月后再重构。

1
2
3
4
5
6
7
8
9
10

这个表把"我推荐方案 A"变成了客观结果——评审人不用听你解释，自己看表就能判断。

# 4.3 灰度发布计划——这是评审人最想看到的

任何有风险的技术变更，如果你在方案里主动写了灰度计划，评审通过率大幅提升：

灰度三步走：
Step 1：单机灰度（1 台机器，观察 1 小时）→ 监控：错误率、P99 延迟
Step 2：10% 流量（观察 1 天）→ 监控：同上 + 业务指标
Step 3：全量发布
回滚条件：Step 1/2 任意阶段错误率 > 基线 × 2，立刻回滚
回滚方式：切回 feature flag / 重新部署上一版本（预计 5 分钟）

1
2
3
4
5
6

灰度计划的价值不只是安全——是让评审人感受到"你想过失败了怎么办"。

# 五、常见技术文档的极简模板

# 5.1 Bug 报告

## 现象
[一句话描述：用户在什么操作下看到了什么]

## 复现步骤
1. [步骤1]
2. [步骤2]
3. [看到的不符合预期的结果]

## 预期行为
[应该是什么样的]

## 环境
App版本: v2.3.1 / 设备: iPhone 14 iOS 18 / 网络: WiFi

## 日志/截图
[贴关键错误日志，不要贴全部]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 5.2 接口文档（给调用方看）

## POST /api/order/cancel

取消一个待支付的订单。

### 请求
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_id | string | 是 | 订单ID |
| reason | string | 否 | 取消原因，最长 200 字 |

### 响应
```json
{ "code": 0, "message": "success" }

1
2
3
4
5
6
7
8
9
10
11
12
13

# 错误码

code	说明
1001	订单不存在
1002	订单已发货，不可取消
1003	重复取消

# 调用示例

curl -X POST https://api.example.com/order/cancel \
  -H "Authorization: Bearer xxx" \
  -d '{"order_id": "12345", "reason": "不想要了"}'

1
2
3


### 5.3 Oncall 记录

```text
## [告警] 支付回调处理延迟 > 3s
时间：2024-01-15 14:30 - 14:55
影响：约 200 个订单的回调处理延迟，用户收到支付成功通知晚了 5-15 分钟

### 根因
第三方支付回调的签名验证逻辑中，公钥获取接口超时（上游 CA 服务故障）

### 临时修复
降级方案：使用本地缓存的公钥（有效期 24h），跳过实时获取

### 长期修复
□ 公钥获取加入本地缓存 + 被动刷新机制
□ 回调处理增加异步化，签名验证失败不影响通知下发

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 六、小结

技术写作的核心能力不是文笔——是换位思考。每次写完问自己：如果我是读者，我能用最快的速度找到我要的信息吗？

写作三原则：

1. 结论先行   → 读者不需要跟着你的思考过程走一遍
2. 对比择优   → 你的方案为什么好？不是什么逻辑推理——是对比出来的
3. 处处为读者省时间 → TL;DR、表格、代码注释、灰度计划——每多一处，读者就少问一个问题

1
2
3
4
5

行动清单：

[ ] 下一次写方案文档，先用 TL;DR 公式写第一段
[ ] 你的 wiki/知识库里找一个旧文档，按"结论先行"原则改一遍——感受差别
[ ] 今天踩了一个坑？花 30 分钟写一个 STAR 格式的博客初稿

#写作

上次更新: 2026/06/15, 14:13:42

← README 技术演讲表达技巧→