夜雨聆风
技术文档不会写?这是一套让团队真正读懂你的最小指南
很多团队的文档问题不是找不到时间去写，而是写出来没人想读。本文给出一套最小指南，教你写出团队真正愿意看的技术文档。
这篇文章解决什么问题
如果你的技术文档存在以下情况：
- • 别人看了还是问同样的问题
- • 自己写的时候感觉在自言自语
- • 文档久了自己都不想再打开
这篇教程教你：在有限时间内，写出让读者能快速取得知识的技术文档。
读完本文，你将能：
- 1. 用 3 个问题确定文档该写什么内容
- 2. 掌握 4 种文档类型，分别适合什么场景
- 3. 写出让读者不用再来问你的 3 个关键要素
- 4. 用最小的检查清单验证文档质量
背景
技术文档的终极目标是：让读者不用向你打听。
区别于面向用户的产品手册，技术文档更需要解决：
- • 这段代码/配置是干嘛的？
- • 如果出问题，应该怎么排查？
- • 接下来要做什么，才能完成任务？
一个好的技术文档应在读者遇到第一个阻碍时，就提供足够的线索继续推进。
前提条件
在阅读本文前，你应具备：
- • ✅ 做过至少一次别人需要阅读的技术文档
- • ✅ 了解 Markdown 或 Confluence 等文档工具
- • ✅ 会用
> 引用块和代码块组织内容
不需要：
- • 大篇幅的设计文档经验
- • 复杂的文档管理体系
第一步：写文档前，先回答三个问题
在开始写之前，用这三个问题核对你是否知道要写什么：
Q1：谁是读者？
- • 新同事？老同事？未来 6 个月后的自己？
- • 他们遇到什么具体问题会来看这篇文档？
Q2：读者看完能做什么？
- • 是安装一个工具？调通一个接口？还是理解一个架构决策？
- • 尽量具体：不要写“理解项目”，而是“能修改某个参数并看到效果”
Q3：如果没这篇文档，会发生什么？
- • 别人问你？出 bug？误用？推翻重来？
如果这三个问题的答案都很模糊，说明你还没准备好写文档。
第二步：选择正确的文档类型
技术文档分为 4 种基本类型，分别适合不同场景：
| 类型 | 适用场景 | 关键要素 |
|---|---|---|
| 指南 (Guide) | 教人做事 | 步骤 + 预期结果 + 排错 |
| 参考 (Reference) | 解释概念 | 定义 + 示例 + 链接 |
| 决策记录 (ADR) | 记录选型 | 背景 + 选项 + 理由 |
| 排查手册 (Runbook) | 处理故障 | 现象 + 检查 + 解决 |
选择原则：
- • 教人做事 → 指南
- • 解释概念 → 参考
- • 记录选型 → 决策记录
- • 处理故障 → 排查手册
第三步：写出让人读的最小结构
不同类型的文档需要的最小结构不同：
指南类（80% 的文档都属于这类）
# 标题：做什么事情的指南
> 总结句：这篇指南帮你完成什么目标，用时多久
## 准备
- 需要什么环境/账号
- 时间预估
## 步骤 1：XXX
```bash
# 命令预期结果：看到什么输出
步骤 2：XXX
…
常见问题
- • 问题现象 → 原因 → 解决
成功标准
- • 完成后应该能做什么
### 参考类
```markdown
# 概念名
## 它是什么
一句话定义 + 核心作用
## 为什么需要
- 解决什么痛点
- 对比不用它的后果
## 如何使用
最小示例 + 常见配置
## 延伸阅读
链接到相关文档/代码决策记录 (ADR)
# ADR-XXX: 选用 XXX 技术
## 状态
提议中 / 接受 / 废弃
## 背景
遇到了什么问题，需要什么能力
## 选项
- 选项 A：优点/缺点
- 选项 B：优点/缺点
- 选项 C：优点/缺点
## 决策
选择选项 X，因为...
## 后果
- 正面影响
- 需要注意的问题排查手册
# 排查手册：XXX 服务超时
## 现象
- 错误日志
- 用户看到的报错
## 检查步骤
1. 检查 A → 预期/不预期
2. 检查 B → 预期/不预期
3. ...
## 常见原因
- 原因 1 → 解决
- 原因 2 → 解决第四步：检查你的文档质量
在发布前，用这个 5 项检查清单：
## 文档质量检查
- [ ] 读者能在 10 秒内知道这篇文档能解决什么问题？
- [ ] 每个步骤都有预期结果？
- [ ] 常见报错至少列出 2 个？
- [ ] 链接都能点击/指向正确的内容？
- [ ] 用 6 个月后的自己测试，还能看懂吗？常见错误
1. 从标题开始就写得太学术
错：采用学术论文的概述模式 对：直接说这篇文档能解决什么具体问题
2. 假设读者知道背景
错：直接从技术细节开始 对：先说明为什么需要这篇文档、谁需要读
3. 列步骤不给结果
错：只写做什么 对：写做什么 + 预期看到什么 + 如果没看到就怎么办
4. 没有维护计划
错：写完就发布，再也不更新 对：注明最后更新时间，或设置定期 review
总结
写好技术文档的核心是：让读者在遇到阻塞时，不需要找你。
- 1. 确定读者和目标：3 个问题快速定位
- 2. 选对文档类型：指南/参考/决策/排查，对应不同场景
- 3. 采用最小结构：每个类型都有固定骨架
- 4. 做质量检查：5 项清单确保可读性
下次写文档前，先问自己：”读完这篇，读者还需要找我问什么？”
如果答案不是 “不需要问了”，那就继续修改。
下一步
你可以把这个框架当作团队的文档规范：
- 1. 在团队共享中保存这篇文章
- 2. 提醒新同事在写文档前看这篇
- 3. 定期 Review 现有文档，补上缺失的要素
最后：好的文档就是最好的同事。让它替代你重复回答同一问题的工作。