---
url: /blog/tech-doc-sop/index.md
---
# 技术文档编写 SOP

> **核心理念**：文档是给读者看的，不是给作者看的。好的技术文档应该**顺应大脑的认知规律**——从全局到局部，从抽象到细节，从问题到方案。
>
> **灵感来源**：ThoughtWorks《如何阅读代码》——代码和文档一样，都是知识的载体，理解它们的路径是相通的。

***

## 1 目的（Purpose）

本 SOP 旨在建立统一的技术文档编写规范，解决以下问题：

* **知识传递效率低**：文档结构混乱、重点不清，读者难以快速获取所需信息
* **质量参差不齐**：缺乏统一标准和检查机制，文档质量依赖个人经验
* **维护成本高**：没有规范的结构模板，文档风格各异，后续维护困难

通过本 SOP，确保产出的技术文档具备**可读性、可执行性、可检查性**。

***

## 2 适用范围（Scope）

### 2.1 适用的文档类型

| 文档类型 | 说明 |
|----------|------|
| 系统介绍文档 | 介绍系统架构、模块、功能的技术文档 |
| 技术方案文档 | 描述技术选型、方案设计、实施计划的文档 |
| API 文档 | 接口定义、参数说明、调用示例 |
| 部署运维文档 | 环境搭建、部署流程、排障手册 |
| 技术分享文档 | 内部分享、知识沉淀类文档 |

### 2.2 不适用范围

* 产品需求文档（PRD）
* 非技术类通知、公告
* 会议纪要
* 个人笔记（未经整理的草稿）

***

## 3 术语定义（Definitions）

| 术语 | 定义 |
|------|------|
| Why-What-How | 技术文档的经典三段式结构：为什么 → 是什么 → 怎么做 |
| 读者画像 | 对目标读者的技术水平、背景知识、阅读目的的预判 |
| 问题驱动 | 以回答读者疑问为导向组织内容，而非堆砌信息 |
| 分层展示 | 先给概览再逐步下钻的展示策略，先 3 万英尺视角再到细节 |
| 渐进式披露 | 从简单到复杂逐步展开信息的方式 |

***

## 4 角色与职责（Roles）

| 角色 | 职责 | 交付物 |
|------|------|--------|
| **编写者** | 按本 SOP 编写文档；明确读者画像；执行自查清单 | 文档初稿、自查通过记录 |
| **审核者** | 审核文档内容的准确性、完整性；从读者视角评估可读性 | 审核意见、修改建议 |
| **批准者** | 确认文档达到发布标准；批准对外发布 | 发布批准 |
| **维护者** | 定期检查文档是否过时；随系统变更同步更新文档 | 更新记录、修订日志 |

> **注**：在小团队中，编写者与审核者可为同一人，但必须间隔至少 24 小时后再自查。

***

## 5 操作流程（Procedure）

### 5.1 核心原则

编写者在整个流程中须遵循以下三条核心原则：

**原则一：读者视角优先**

文档写得好不好，读者说了算。写之前先回答以下问题：

| 问题 | 目的 |
|------|------|
| 读者是谁？初级/高级/领域专家？ | 决定解释的深度 |
| 读者带着什么问题来？ | 决定内容的重点 |
| 读者看完能做什么？ | 决定输出物的形式 |
| 读者最可能卡在哪里？ | 决定详略取舍 |

**原则二：从全局到局部**

大脑理解新事物的规律是：先有地图，再探索细节。

```
错误路径：直接上代码细节 → 读者迷失
正确路径：概述 → 架构 → 模块 → 细节
```

**原则三：问题驱动**

好的技术文档是回答问题的，不是堆砌信息的。每个章节应对应读者心中的一个疑问，章节标题最好就是读者会问的问题。

### 5.2 流程步骤

#### 步骤 1：准备阶段

| 项目 | 说明 |
|------|------|
| **输入** | 文档需求、目标读者信息、相关代码/系统访问权限 |
| **活动** | 明确读者画像；列出读者可能问的 5-10 个问题；收集必要素材（代码、配置、截图）；画好核心架构图草图 |
| **输出** | 读者画像说明、问题清单、素材文件夹、架构草图 |
| **交付物** | 文档编写计划（含读者画像和问题清单） |

#### 步骤 2：编写 Why 部分（为什么存在）

| 项目 | 说明 |
|------|------|
| **输入** | 步骤 1 的输出 |
| **活动** | 描述背景与痛点；阐明要解决的核心问题；说明为什么现有方案不够好（如有对比）；用场景讲故事，让读者产生共鸣 |
| **输出** | Why 章节初稿 |
| **质量要求** | 一句话说清楚价值主张；读者读完后能理解"为什么要做这件事" |

**示例**：

> 在没有 XX 之前，团队需要手动配置 20+ 个文件，每次上线耗时 2 小时。XX 系统通过模板化配置，将上线时间缩短到 10 分钟。

#### 步骤 3：编写 What 部分（是什么）

| 项目 | 说明 |
|------|------|
| **输入** | Why 章节、系统/方案的架构信息 |
| **活动** | 绘制整体架构图；解释核心概念；划分模块与职责；描述关键流程 |
| **输出** | What 章节初稿、配套图表 |
| **质量要求** | 必须包含至少一张架构图；第一次出现的术语必须有定义；分层展示，先概览再下钻 |

**图表类型参考**：

| 图表类型 | 适用场景 | 粒度建议 |
|----------|----------|----------|
| 架构图 | 展示系统组成和模块关系 | 展示核心模块，省略细节 |
| 流程图 | 展示业务流程或数据流向 | 主路径 + 2-3 个关键分支 |
| 时序图 | 展示模块间交互顺序 | 一次只画一个场景 |
| 状态图 | 展示状态流转 | 关注核心状态，忽略中间态 |
| ER 图 | 展示数据模型 | 展示核心实体关系 |

> **图表原则**：一张图只讲一件事，多张小图优于一张大图。图的目的是帮助理解，不是还原真实。

#### 步骤 4：编写 How 部分（怎么用/怎么实现）

| 项目 | 说明 |
|------|------|
| **输入** | What 章节、系统使用/实现细节 |
| **活动** | 编写快速开始（5 分钟能跑起来的最小示例）；编写详细使用说明；选取关键实现细节；编写常见问题与排错指南 |
| **输出** | How 章节初稿、可运行的示例代码 |
| **质量要求** | 示例代码必须能跑通；从简单到复杂渐进式展示；说明边界（什么能做、什么不能做、坑在哪里） |

**代码引用原则**：代码是为了说明观点，不是为了展示实现。

| 做法 | 说明 |
|------|------|
| 推荐贴核心逻辑 | 展示关键设计思想 |
| 推荐贴使用示例 | 帮助读者上手 |
| 禁止全量粘贴 | 读者会跳过 |
| 禁止贴无关代码 | 干扰注意力 |

> **技巧**：用伪代码 + 关键代码片段，配合文字说明。

#### 步骤 5：自查与修改

| 项目 | 说明 |
|------|------|
| **输入** | 文档完整初稿 |
| **活动** | 按「第 7 节 质量检查」逐项检查；修改不通过项 |
| **输出** | 自查通过的文档 |
| **交付物** | 自查清单（已勾选通过） |

#### 步骤 6：审核与发布

| 项目 | 说明 |
|------|------|
| **输入** | 自查通过的文档 |
| **活动** | 提交审核者评审；审核者从读者视角评估；根据反馈修改；批准者确认发布 |
| **输出** | 终稿、发布版本 |
| **交付物** | 审核通过的正式文档 |

> **审核建议**：找一个不了解项目的人读一遍，看他卡在哪里，就是文档需要改进的地方。

***

## 6 文档模板（Template）

### 6.1 系统介绍文档模板

```markdown
# XX 系统介绍

## 背景（Why）
- 解决什么问题
- 为什么需要这个系统

## 架构（What）
- 整体架构图
- 核心模块说明
- 关键流程图

## 使用指南（How）
- 快速开始
- 详细配置
- 常见问题
```

### 6.2 技术方案文档模板

```markdown
# XX 技术方案

## 问题分析（Why）
- 当前痛点
- 目标状态

## 方案设计（What）
- 整体设计图
- 核心设计点
- 方案对比（如有）

## 实施计划（How）
- 分阶段实施步骤
- 风险与应对
- 验收标准
```

### 6.3 API 文档模板

```markdown
# XX API

## 概述
- 功能说明
- 使用场景

## 接口列表
| 接口 | 方法 | 说明 |
|------|------|------|

## 接口详情
### 接口名
- 请求参数
- 返回示例
- 错误码

## 快速示例
```

***

## 7 质量检查（Quality Checks）

### 7.1 结构检查

| 序号 | 检查项 | 通过标准 | 是否通过 |
|------|--------|----------|----------|
| 1 | 是否包含 Why-What-How 三个部分 | 三个部分完整，缺一不可 | \[ ] |
| 2 | 标题是否就是读者会问的问题 | 标题能直接对应一个读者疑问 | \[ ] |
| 3 | 内容顺序是否符合从全局到局部 | 先概述再细节，无跳跃 | \[ ] |

### 7.2 可读性检查

| 序号 | 检查项 | 通过标准 | 是否通过 |
|------|--------|----------|----------|
| 4 | 没看代码的人能看懂吗？ | 非项目成员可理解核心内容 | \[ ] |
| 5 | 有没有自造词没解释？ | 首次出现的术语都有定义 | \[ ] |
| 6 | 重点内容是否突出？ | 关键信息有加粗或提示框标注 | \[ ] |

### 7.3 图表检查

| 序号 | 检查项 | 通过标准 | 是否通过 |
|------|--------|----------|----------|
| 7 | What 部分是否有架构图 | 至少一张架构图 | \[ ] |
| 8 | 图表能独立表达含义吗？ | 不看正文也能理解图表信息 | \[ ] |
| 9 | 一张图是否只讲一件事？ | 每张图聚焦单一主题 | \[ ] |

### 7.4 代码检查

| 序号 | 检查项 | 通过标准 | 是否通过 |
|------|--------|----------|----------|
| 10 | 代码示例能直接运行吗？ | 复制粘贴即可执行 | \[ ] |
| 11 | 是否避免全量代码粘贴？ | 只保留核心逻辑和使用示例 | \[ ] |
| 12 | 是否渐进式展示？ | 从简单到复杂排列 | \[ ] |

### 7.5 读者适配检查

| 序号 | 检查项 | 通过标准 | 是否通过 |
|------|--------|----------|----------|
| 13 | 背景知识是否按读者水平处理？ | 初级放附录、中级简要+链接、高级省略 | \[ ] |
| 14 | 读者看完知道下一步做什么吗？ | 有明确的行动指引或示例 | \[ ] |

***

## 8 常见问题处理指南

### 8.1 代码要不要贴？贴多少？

代码是为了说明观点，不是为了展示实现。推荐贴核心逻辑和使用示例，禁止全量粘贴和贴无关代码。用伪代码 + 关键代码片段，配合文字说明。

### 8.2 图画多细？

图的目的是帮助理解，不是还原真实。架构图展示核心模块省略细节，流程图画主路径 + 2-3 个关键分支，时序图一次只画一个场景。一张图只讲一件事，多张小图优于一张大图。

### 8.3 要不要写背景知识？

根据读者类型判断：

| 读者类型 | 背景知识处理 |
|----------|--------------|
| 初级 | 要写，放在附录或链接 |
| 中级 | 简要提及 + 链接 |
| 高级 | 不写，直接进主题 |

***

## 9 参考文档（References）

| 序号 | 文档名称 | 说明 |
|------|----------|------|
| 1 | ThoughtWorks《如何阅读代码》 | 核心理念来源：代码和文档都是知识载体 |
| 2 | Divio 文档系统 | 四类文档划分：教程、指南、参考、解释 |

***

## 10 修订记录（Revision History）

| 版本 | 日期 | 修订人 | 修订内容 |
|------|------|--------|----------|
| v1.0 | 2026-03-22 | — | 初版发布：核心原则、Why-What-How 结构、写作流程、模板 |
| v2.0 | 2026-05-11 | — | 重构为标准 SOP 格式：增加目的、范围、术语、角色、质量检查清单、修订记录 |

***

> 写文档的过程，也是梳理自己理解的过程。能清楚地讲给别人听，才是真正掌握了。
>
> —— 灵感来自《如何阅读代码》，代码和文档，殊途同归。

**核心优先级**：

* 读者视角 > 作者视角
* 图表 > 大段文字
* 问题驱动 > 信息堆砌
* 能跑的代码 > 看不懂的代码