文档改动的评审重点
文档评审的重点和代码不同：事实准确性（命令、参数、默认值、版本号）、示例能否照着跑通、结构是否便于扫读、链接是否有效。最有效的验收方式只有一个——照着文档从头操作一遍，看能否得到描述中的结果。
基本信息
| 事实核验 | 命令、参数、默认值、版本数字逐项对照来源 |
|---|---|
| 示例验收 | 复制粘贴之后能复现描述中的结果 |
| 结构要求 | 先结论后细节，标题层级清晰可扫读 |
| 链接检查 | 失效链接是常见的低质信号 |
典型使用场景
- 快速入门文档：确认按顺序操作真的能跑通
- 升级说明：核对破坏性变更与迁移步骤是否完整
- 接口参考：对照代码确认参数与返回值没有变化
- 排错指南：确认报错信息与解决方案一一对应
- 翻译与润色：重点看术语是否统一，不要去改技术事实
评审时逐项核对什么
- 命令是否可直接执行，参数是否写清默认值
- 示例输出与描述是否一致
- 版本号与发布日期是否与当前代码相符
- 被引用页面的链接是否仍然有效
可执行的验收方式
可执行的验收方式
# 照文档跑一遍最小示例
make install && make run-example
# 检查文档里的链接是否有效
lychee --offline docs/
# 文档改动同样走改动评审，便于对照版本历史文档问题与后果
| 问题 | 后果 |
|---|---|
| 版本号过期 | 用户按旧参数操作，第一步就报错 |
| 示例不能运行 | 用户复制后失败，信任度迅速下降 |
| 步骤缺一环 | 按文档操作中途卡住，只能放弃 |
| 链接失效 | 读者找不到背景材料，阅读被中断 |
文档改动同样要走评审流程：发布前跑一次链接检查与拼写检查，成本很低但收益很明确。
在评审中的用法：文档改动附上实际执行过的命令与输出，评审者据此核对描述是否与事实一致。
把示例代码集中管理并纳入测试：能在流水线里跑通的示例，长期看比人工核验更可靠。
只改错别字不看事实：过期的版本号比错别字更容易把人带进坑里。