写作：资深工程师的隐藏超能力

那个被拒的PR

三年前，我提交了一个自认为很棒的 PR：重构了核心业务逻辑，代码更简洁，性能提升了20%。

Reviewer 的回复只有一句话：

“我不理解为什么要做这个改动。”

我满腹委屈——代码明明很清晰，注释也写了，性能提升数据都有。为什么就是看不懂？

后来我的 Mentor 告诉我：“好的代码需要好的故事。你写代码花了3天，但写PR描述只花了3分钟。”

那一刻我意识到：写作不是锦上添花，而是工程师的核心技能。

为什么写作是超能力

1. 写作是思考的延伸

“写不清楚，是因为想不清楚。” —— 威廉·津瑟

现象：

写代码时觉得思路清晰，一写文档就卡壳
开会时能表达，但写会议纪要就遗漏要点
做方案时想了很多，写出来却逻辑混乱

真相：写作强迫你结构化思考。只有能清晰地写下来，才说明你真正理解了。

2. 写作是异步沟通的基石

远程工作和跨时区协作让同步沟通成本极高。

数据：

沟通方式	效率	可持久化	覆盖范围
面对面	高	低	1-2人
视频会议	中	低	5-10人
即时消息	中	中	10-20人
文档	低	高	无限

写作的优势：

一次写作，无限次阅读
跨越时区和语言
沉淀为组织知识资产
减少重复解释

3. 写作是影响力的放大器

个人影响力公式：

影响力 = 专业深度 × 传播广度

代码再优雅，只有 Reviewer 能看到
架构再优秀，只有团队成员能理解
想法再棒，只在你的脑子里

写作让影响力突破物理边界：

一篇技术博客 → 千人阅读
一份RFC → 影响整个团队决策
一本技术书籍 → 万人受益

工程师的三类写作

第一类：事务性写作（日常沟通）

场景：PR描述、Issue评论、Slack消息、邮件

问题：

❌ 不好的PR描述：
"修复了登录bug，优化了代码。"

✅ 好的PR描述：
## 问题
用户在弱网环境下登录时，由于重试机制缺失，
导致多次点击"登录"按钮产生重复请求（#1234）。

## 解决方案
添加防抖处理，500ms内重复点击无效。
同时添加 loading 状态防止用户重复操作。

## 改动范围
- src/components/LoginForm.tsx
- src/hooks/useDebounce.ts (新增)

## 测试
- [x] 弱网环境测试（3G模拟）
- [x] 单元测试覆盖
- [x] 多端兼容性测试

原则：

前置结论：先说结果，再说过程
背景信息：提供必要的上下文
明确行动：对方需要做什么

第二类：知识性写作（文档沉淀）

场景：技术文档、API文档、Onboarding指南、决策记录(ADR)

框架：Diátaxis文档模型

技术文档
├── 教程(Tutorials)：手把手教新人入门
├── 操作指南(How-to Guides)：解决特定问题
├── 参考文档(Reference)：API/配置详细说明
└── 解释说明(Explanation)：概念和原理讲解

实战示例：Onboarding文档

# 后端开发上手指南

## 第一天：环境搭建
### 目标
在本地跑通开发环境，成功启动服务。

### 步骤
1. 克隆仓库
2. 安装依赖
3. 配置环境变量
4. 启动服务

### 验证
运行 `curl http://localhost:3000/health`，
应返回 `{"status": "ok"}`。

### 常见问题
- **端口被占用**：修改 `.env` 中的 `PORT`
- **数据库连接失败**：确认本地PostgreSQL已启动

## 第一周：第一个任务
### 建议
从简单的 bug fix 开始，熟悉代码结构和流程。

### 推荐任务标签
- `good first issue`
- `difficulty: low`

## 第一个月：独立负责模块
### 目标
能够独立完成中等复杂度的功能开发。

### 检查清单
- [ ] 熟悉核心代码结构
- [ ] 理解CI/CD流程
- [ ] 完成至少一个功能开发
- [ ] 进行一次技术分享

第三类：说服性写作（推动决策）

场景：RFC（Request for Comments）、技术方案、晋升答辩、项目复盘

核心挑战：不是”写清楚”，而是”说服他人”。

框架：SCQA模型

S - Situation（情境）：我们当前的情况
C - Complication（冲突）：遇到的问题
Q - Question（问题）：我们需要解决什么
A - Answer（答案）：我的方案

实战示例：微服务拆分RFC

# RFC: 用户服务拆分

## 背景(Situation)
当前单体架构已服务3年，支撑日活从1万到100万。
代码库规模：
- 后端代码：15万行
- 部署频率：每周1次
- 构建时间：15分钟

## 问题(C)
近半年遇到以下挑战：
1. **发布耦合**：一个小改动需要全量回归测试
2. **团队协作**：20人同时修改代码，冲突频繁
3. **故障隔离**：局部故障影响全局
4. **技术栈锁定**：难以引入新技术

## 问题(Q)
如何在不影响业务的前提下，逐步拆分用户服务，
实现独立开发、独立部署、独立扩展？

## 方案(A)
### 拆分策略
采用"绞杀模式"，逐步迁移：

Phase 1 (1-2月)：
- 提取用户认证模块
- 独立部署，流量1%切流

Phase 2 (2-3月)：
- 提取用户资料模块
- 独立部署，流量10%切流

Phase 3 (3-4月)：
- 全量切流
- 下线原单体代码

### 架构图
[架构图]

### 风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 数据一致性 | 中 | 高 | 引入Saga模式 |
| 性能下降 | 低 | 中 | 缓存策略优化 |
| 团队学习成本 | 高 | 低 | 提前培训 |

### 成功指标
- 服务独立部署时间 < 5分钟
- 发布频率提升到每天1次
- P99响应时间 < 200ms

提升写作能力的四个练习

练习一：PR描述升级

Before：

修复了登录问题

After：

## 问题
Fixes #2341

在iOS Safari上，登录按钮点击无响应。
复现步骤：
1. iOS Safari打开登录页
2. 输入正确账号密码
3. 点击登录按钮
4. 预期：进入首页，实际：无响应

## 原因
Safari对Date对象解析与Chrome不同，
导致token过期判断逻辑错误。

## 解决方案
统一使用ISO 8601格式解析日期，
添加浏览器兼容性测试。

## 测试
- [x] iOS Safari (iPhone 14, iOS 17)
- [x] Android Chrome (Pixel 7)
- [x] 桌面Chrome/Edge/Firefox

行动：接下来的10个PR，每个PR描述写至少100字。

练习二：文档驱动开发

原则：先写文档，再写代码。

流程：

需求 → 写设计文档 → 评审 → 写代码 → 补充文档

模板：

## API设计文档

### 功能
[一句话描述]

### 接口

POST /api/v1/resource


### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|

### 响应
| 字段 | 类型 | 说明 |
|------|------|------|

### 错误码
| 码 | 说明 |
|----|------|

### 验收标准
- [ ] 功能实现
- [ ] 单元测试覆盖>80%
- [ ] API文档更新
- [ ] 错误监控配置

练习三：技术博客写作

好处：

强迫深入理解
建立个人品牌
帮助他人
面试时的加分项

起步建议：

每周一篇
从”我本周解决的问题”开始
不求完美，先求完成

结构模板：

1. 问题背景（为什么要写这个）
2. 踩坑过程（真实经历）
3. 解决方案（代码+解释）
4. 总结（可复用的经验）

练习四：会议纪要和复盘

会议纪要的3C原则：

Context（背景）：会议目的和议题
Conclusion（结论）：达成的共识和决策
Commitment（承诺）：行动项和负责人

复盘文档结构：

# 项目复盘：XX功能上线

## 背景
项目目标、时间线、团队组成

## 结果
- 预期 vs 实际
- 数据指标

## 做得好
1. ...
2. ...

## 待改进
1. ...
2. ...

## 行动项
- [ ] @负责人 具体行动 (截止日期)

常用写作框架

框架一：金字塔原理

结论先行
├── 论据1
│   ├── 事实A
│   └── 事实B
├── 论据2
│   ├── 事实C
│   └── 事实D
└── 论据3
    ├── 事实E
    └── 事实F

应用场景：技术方案、汇报材料

框架二：PREP

P - Point（观点）：我要说什么
R - Reason（理由）：为什么这么说
E - Example（例子）：具体案例
P - Point（重申）：再强调一次观点

应用场景：技术分享、演讲稿

框架三：5W2H

What：做什么
Why：为什么做
Who：谁来做
When：什么时候做
Where：在哪里做
How：怎么做
How much：成本是多少

应用场景：项目计划、任务分配

提升写作质量的技巧

技巧一：删减50%

原则：第一稿写完，删掉50%的内容。

删减对象：

废话和套话（“众所周知”、“显然”）
重复表达
不必要的修饰词

示例：

❌ "我们在这个项目中取得了非常显著的成果，
    这些成果对于公司的业务发展具有重要的意义。"

✅ "项目成果：转化率提升15%，带来年增收200万。"

技巧二：用数字说话

比较：

❌ "性能大幅提升"
✅ "响应时间从800ms降至150ms，提升81%"

❌ "很多人使用"
✅ "日活跃用户12万，月活跃用户80万"

❌ "很快"
✅ "3天内完成部署"

技巧三：可视化

一图胜千言：

架构图代替文字描述
流程图代替步骤说明
对比表代替并列叙述

工具推荐：

Excalidraw：手绘风格图表
Draw.io：专业流程图
Mermaid：代码生成图表

技巧四：读者视角

写作前问自己：

读者是谁？（技术背景、角色）
读者关心什么？（痛点、利益点）
读者预期看到什么？（结论、方案、数据）

技术写作常见错误：

❌ 过度使用缩写而不解释
❌ 假设读者了解上下文
❌ 使用模糊的代词（"这个"、"那个"）
❌ 长段落（超过5行不分段）

写作工具推荐

文本编辑

VS Code + Markdown插件：技术文档首选
Notion：团队协作文档
Obsidian：个人知识库
Grammarly：英文语法检查

图表绘制

Excalidraw：快速手绘风格图表
Draw.io：专业架构图
PlantUML：代码生成UML
Mermaid：Markdown内嵌图表

版本管理

Git：文档即代码
Markdown：格式统一
GitHub/GitLab：Review和协作

建立写作习惯

每日习惯

晨间写作：15分钟自由写作（记录想法）
工作记录：随时记录问题和解决方案

每周习惯

周记：本周学习和踩坑
PR描述：每个PR都认真写

每月习惯

技术博客：至少一篇
文档维护：更新过时的文档

写作时间块

早上（精力充沛）：深度写作（方案、博客）
下午（碎片时间）：事务性写作（PR、评论）
晚上（放松状态）：阅读和学习

常见写作障碍与克服

障碍一：完美主义

症状：

总觉得写得不够好，不敢发布
反复修改，无法完成

解药：

“完成比完美更重要。”

实践：

设定时间限制（博客2小时必须发布）
接受”80分就好”
先发布，后迭代

障碍二：不知道写什么

解药：

写”我今天解决的问题”
写”我踩过的坑”
写”我学到的技巧”
写”我对XX的看法”

灵感来源：

Stack Overflow回答过的问题
Code Review中的讨论
和同事的争论
读书/文章的感想

障碍三：没时间写

真相：不是没时间，而是没优先级。

策略：

把写作当作任务，排入日程
利用碎片时间（通勤、等待）
减少无效会议（省下的时间用于写作）

写作能力的复利效应

短期（1-3个月）

PR通过率提升
Code Review质量提高
团队沟通更高效

中期（6-12个月）

建立个人技术品牌
获得演讲/培训机会
晋升为Tech Lead

长期（2-5年）

出版技术书籍
成为领域专家
影响力突破公司边界

给不同阶段工程师的建议

初级（0-2年）

重点：清晰表达

练习：

每个PR写详细的描述
写Onboarding心得
记录踩过的坑

目标：让他人能理解你的代码和思路

中级（2-5年）

重点：结构化写作

练习：

写技术方案和设计文档
撰写Code Review指南
开始技术博客

目标：推动团队决策，沉淀最佳实践

高级（5年+）

重点：影响力写作

练习：

写RFC推动架构演进
撰写技术战略文档
出版文章或书籍

目标：定义方向，培养他人

结语

代码决定了系统的功能，写作决定了系统的影响力。

一个工程师的价值，不仅仅在于他能写出多少行代码，更在于他能通过写作：

让代码被理解和维护
让想法被接受和实现
让知识被传播和复用
让影响力被放大和持续

“The code you write today will be replaced next year. The documentation you write will live forever.”

开始写作吧，从今天开始。