文档评审清单

文档评审关注技术文档的质量——准确性、完整性、清晰度、可维护性。好的文档能降低沟通成本、加速新人上手、减少重复问题。坏的文档比没有文档更糟（给人错误信心，然后踩坑）。

要点

文档评审关注准确性、完整性、清晰度、可维护性
坏的文档比没有文档更糟（给人错误信心）
重点检查：代码示例能跑、信息是最新的、步骤可跟着做
文档要有负责人和维护计划

1. 适用时机

新文档发布（技术方案、API 文档、用户指南）
现有文档重大更新（架构变化、流程变更）
文档定期复审（每半年或一年）
事故复盘后（补充事故文档、Runbook）
新人入职后（根据新人反馈改进文档）

不需要文档评审的场景：

临时笔记、草稿
一次性沟通记录（会议纪要可以简略）
自动生成的文档（API Schema、类型定义）

2. 评审前准备

[ ] 文档目标读者：谁会读这份文档？（新人、外部用户、运维、管理层）
[ ] 文档类型：是教程、参考、概念解释、还是操作手册？
[ ] 文档范围：覆盖哪些内容？不覆盖哪些内容？
[ ] 相关背景：相关的代码、系统、流程在哪里？
[ ] 历史反馈：之前的读者有什么反馈？

3. 核心检查项

3.1 目标与读者

[ ] 文档目标明确（读完这份文档，读者能做什么？）
[ ] 目标读者明确（写给谁看？假设读者有什么背景知识？）
[ ] 前置条件说明（读者需要具备什么知识/权限？）
[ ] 非目标说明（这份文档不解决什么问题？）

3.2 准确性

[ ] 技术细节准确（代码示例能跑、命令正确、配置有效）
[ ] 信息是最新的（不反映过时的状态、API、流程）
[ ] 数字、日期、版本号正确
[ ] 链接有效（不指向已删除或迁移的资源）
[ ] 截图、图表与实际界面一致

文档准确性检查示例

typescript

// 坏的文档：代码示例跑不通
// "使用以下代码创建用户："
// const user = createUser({ name: 'John' })  // createUser 不存在

// 好的文档：代码示例可运行
// "使用以下代码创建用户："
import { Hono } from 'hono'

const app = new Hono()

app.post('/users', async (c) => {
  const body = await c.req.json()
  const user = await c.env.DB.prepare('INSERT INTO users (name) VALUES (?)')
    .bind(body.name)
    .run()
  return c.json(user)
})

// 验证文档中的命令
// 文档说："运行以下命令部署"
// wrangler deploy  // 这个命令应该能跑通

3.3 完整性

[ ] 覆盖主路径（正常情况下的完整流程）
[ ] 覆盖失败路径（出错时怎么办？）
[ ] 覆盖边界情况（特殊场景、例外处理）
[ ] 包含示例（代码、命令、配置、截图）
[ ] 包含故障排查（常见问题及解决方法）
[ ] 包含相关资源链接（深入学习的材料）

3.4 清晰度

[ ] 结构清晰（章节划分合理、层次分明）
[ ] 语言简洁（不啰嗦、不绕弯）
[ ] 术语一致（同一概念用同一个词）
[ ] 术语解释（专业术语第一次出现时有解释）
[ ] 步骤有序（操作指南按顺序编号）
[ ] 重点突出（关键信息用粗体、警告框、注意框）

3.5 可操作性

[ ] 操作指南可跟着做（步骤完整、可执行）
[ ] 命令可以直接复制粘贴（不遗漏参数）
[ ] 预期结果明确（做完一步应该看到什么）
[ ] 错误处理说明（出错了怎么办）
[ ] 验证方式（怎么判断做成功了）

可操作文档示例

markdown

## 部署步骤

### 前置条件
- 已安装 Node.js 18+
- 已安装 pnpm
- 已有 Cloudflare 账号

### 步骤 1：安装依赖

\`\`\`bash
pnpm install
\`\`\`

**预期结果**：看到 `Done in 2.5s`

### 步骤 2：配置环境变量

创建 `.env` 文件：

\`\`\`bash
cp .env.example .env
\`\`\`

编辑 `.env`，填入你的 Cloudflare API Token：

\`\`\`
CLOUDFLARE_API_TOKEN=your_token_here
\`\`\`

**获取 Token**：登录 Cloudflare Dashboard → My Profile → API Tokens → Create Token

### 步骤 3：部署

\`\`\`bash
pnpm deploy
\`\`\`

**预期结果**：看到 `Deployed to https://my-app.workers.dev`

### 步骤 4：验证

访问 https://my-app.workers.dev，应该看到 "Hello World"

**如果失败**：
- 检查 API Token 是否正确
- 检查网络连接
- 运行 `wrangler tail` 查看日志

3.6 格式与风格

[ ] 符合团队文档风格指南（标题层级、列表格式、代码块语言标注）
[ ] 中英文排版规范（空格、标点、专有名词）
[ ] 图表清晰（有标题、有标注、有来源）
[ ] 代码格式正确（语法高亮、缩进一致）
[ ] 链接格式统一（相对路径 vs 绝对路径）

中英文排版规范示例

markdown

## 坏的排版
使用Hono框架开发Cloudflare Workers应用,需要Node.js18+版本。

## 好的排版
使用 Hono 框架开发 Cloudflare Workers 应用，需要 Node.js 18+ 版本。

规则：
- 中英文之间加空格：使用 Hono 框架
- 数字与中文之间加空格：Node.js 18+ 版本
- 使用中文标点：，。、；：""''
- 专有名词保持原样：Node.js、Cloudflare、Workers

3.7 可维护性

[ ] 负责人明确（谁负责维护这份文档？）
[ ] 更新时间记录（最后更新是什么时候？）
[ ] 更新触发条件明确（什么情况下需要更新？）
[ ] 复审周期（多久检查一次是否过时？）
[ ] 反馈渠道（读者发现问题怎么反馈？）

文档元信息示例

markdown

---
title: 部署指南
author: 白川
createdAt: 2026-01-01
updatedAt: 2026-06-21
maintainer: @zhangsan
review_cycle: 6 months
---

# 部署指南

## 更新记录
- 2026-06-21 更新部署命令（wrangler v3）
- 2026-03-15 添加故障排查章节
- 2026-01-01 初始版本

## 反馈问题
如果发现文档有误，请：
1. 提 Issue：https://github.com/xxx/docs/issues
2. 或联系维护者 @zhangsan

3.8 可发现性

[ ] 文档位置合理（放在读者能找到的地方）
[ ] 标题和关键词便于搜索
[ ] 交叉引用完整（相关文档互相链接）
[ ] 目录清晰（长文档有目录）
[ ] 索引或标签（便于分类检索）

3.9 包容性与可访问性

[ ] 语言中立（不排斥特定群体）
[ ] 图片有 alt 文本（便于屏幕阅读器）
[ ] 颜色对比度足够（色弱用户可阅读）
[ ] 链接描述有意义（不用「点击这里」）

4. 文档类型特定检查

4.1 API 文档

[ ] 所有接口都有描述
[ ] 请求和响应示例完整
[ ] 错误码列表及含义
[ ] 认证方式说明
[ ] 限流策略说明
[ ] 版本历史和变更日志

API 文档示例

markdown

## POST /api/v1/users

创建新用户。

### 认证
需要 Bearer Token（管理员权限）

### 请求

**Headers**
\`\`\`
Authorization: Bearer <token>
Content-Type: application/json
\`\`\`

**Body**
\`\`\`json
{
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "user"
}
\`\`\`

**字段说明**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 用户姓名，1-100 字符 |
| email | string | 是 | 邮箱地址，必须唯一 |
| role | string | 否 | 角色，默认 "user"，可选 "admin" |

### 响应

**201 Created**
\`\`\`json
{
  "id": "usr_abc123",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "user",
  "createdAt": "2026-06-21T10:00:00Z"
}
\`\`\`

**400 Bad Request**
\`\`\`json
{
  "code": "VALIDATION_ERROR",
  "message": "请求参数校验失败",
  "details": [
    { "field": "email", "message": "邮箱格式不正确" }
  ]
}
\`\`\`

**409 Conflict**
\`\`\`json
{
  "code": "EMAIL_EXISTS",
  "message": "邮箱已被注册"
}
\`\`\`

### 限流
- 每用户每分钟 10 次
- 超限返回 429 Too Many Requests

### 示例

**curl**
\`\`\`bash
curl -X POST https://api.example.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "张三", "email": "zhangsan@example.com"}'
\`\`\`

4.2 操作手册 / Runbook

[ ] 前置条件明确（需要什么权限、工具）
[ ] 步骤可跟着做（顺序正确、可执行）
[ ] 预期结果明确（每步做完应该看到什么）
[ ] 故障排查（常见问题及解决）
[ ] 回滚方案（操作失败怎么恢复）
[ ] 联系方式（出问题找谁）

4.3 技术方案 / 设计文档

[ ] 背景和目标明确
[ ] 方案描述清晰（有图、有代码示例）
[ ] 取舍说明（为什么选这个方案）
[ ] 风险评估
[ ] 实施计划
[ ] 验证方式

4.4 教程 / 入门指南

[ ] 从零开始（假设读者什么都不知道）
[ ] 步骤完整（不跳步）
[ ] 示例可运行（代码能跑、环境能搭）
[ ] 循序渐进（从简单到复杂）
[ ] 练习和检验（让读者验证学到的东西）

5. 评审会上容易漏的点

目标读者：问「这份文档写给谁看？他们有什么背景？」
准确性验证：问「里面的代码示例你实际跑过吗？」
可操作性：问「新人能跟着这份文档做成功吗？」
维护责任：问「这份文档谁来维护？多久更新一次？」
反馈渠道：问「读者发现问题怎么反馈？」

6. 通过标准

[ ] 目标读者明确，内容匹配读者水平
[ ] 技术细节准确、信息最新
[ ] 覆盖完整（主路径 + 失败路径 + 边界）
[ ] 结构清晰、语言简洁
[ ] 操作指南可跟着做
[ ] 维护责任明确

7. 反模式

以下是文档的反模式：

假设读者知道：跳过关键步骤，「这个很简单，读者应该知道」
复制粘贴代码：代码示例没验证，跑不通
信息过时：文档还引用已删除的 API 或已变更的流程
只写主路径：不写出错怎么办，读者一碰壁就卡住
没人维护：写完就扔，越来越过时
过于冗长：废话太多，读者找不到重点

8. 维护建议

文档评审清单需要随团队实践更新：

文档工具变化时（如从 Confluence 切到 Notion），调整相关检查项
出现文档相关的问题后（新人被错误文档误导），把根因对应的检查项加进来
团队规模扩大时，强化可发现性和维护责任要求
每半年复审一次，删除过时的检查项

文档评审清单 ​

要点 ​

1. 适用时机 ​

2. 评审前准备 ​

3. 核心检查项 ​

3.1 目标与读者 ​

3.2 准确性 ​

3.3 完整性 ​

3.4 清晰度 ​

3.5 可操作性 ​

3.6 格式与风格 ​

3.7 可维护性 ​

3.8 可发现性 ​

3.9 包容性与可访问性 ​

4. 文档类型特定检查 ​

4.1 API 文档 ​

4.2 操作手册 / Runbook ​

4.3 技术方案 / 设计文档 ​

4.4 教程 / 入门指南 ​

5. 评审会上容易漏的点 ​

6. 通过标准 ​

7. 反模式 ​

8. 维护建议 ​

文档评审清单

要点

1. 适用时机

2. 评审前准备

3. 核心检查项

3.1 目标与读者

3.2 准确性

3.3 完整性

3.4 清晰度

3.5 可操作性

3.6 格式与风格

3.7 可维护性

3.8 可发现性

3.9 包容性与可访问性

4. 文档类型特定检查

4.1 API 文档

4.2 操作手册 / Runbook

4.3 技术方案 / 设计文档

4.4 教程 / 入门指南

5. 评审会上容易漏的点

6. 通过标准

7. 反模式

8. 维护建议