技术文档编写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 系统介绍文档模板
# XX 系统介绍
## 背景（Why）
- 解决什么问题
- 为什么需要这个系统
## 架构（What）
- 整体架构图
- 核心模块说明
- 关键流程图
## 使用指南（How）
- 快速开始
- 详细配置
- 常见问题6.2 技术方案文档模板
# XX 技术方案
## 问题分析（Why）
- 当前痛点
- 目标状态
## 方案设计（What）
- 整体设计图
- 核心设计点
- 方案对比（如有）
## 实施计划（How）
- 分阶段实施步骤
- 风险与应对
- 验收标准6.3 API 文档模板
# 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 格式：增加目的、范围、术语、角色、质量检查清单、修订记录 |
写文档的过程，也是梳理自己理解的过程。能清楚地讲给别人听，才是真正掌握了。
—— 灵感来自《如何阅读代码》，代码和文档，殊途同归。
核心优先级：
- 读者视角 > 作者视角
- 图表 > 大段文字
- 问题驱动 > 信息堆砌
- 能跑的代码 > 看不懂的代码