先找对读者有影响的行为
对照改动前后的测试、类型、默认值和界面,记录读者在什么条件下看到什么变化。调整标题搜索排序时,核对结果顺序和案例。变量更名且仍兼容旧值时,更新首选写法并说明兼容边界。
能通过文档判断的事情包括引入版本、可用平台、启用方式、默认值、优先级、输出结构和错误。代码整理只涉及内部实现时,可以验证现有示例是否继续成立。需要跨版本发布时,确认要更新的是稳定版、下一版本还是两者。
顺着使用路径检查页面
| 改动 | 优先检查的文档 |
|---|---|
| 新增参数或公开函数 | API 或配置参考、调用示例、安装或接入指南 |
| 用户可见的修复 | 受影响的故障排查、示例输出、版本说明 |
| 启用方式或默认值改变 | 首次使用步骤、配置参考、升级指南 |
| 删除字段或旧行为 | 迁移条目、弃用提示、引用该字段的旧示例 |
| 报错条件或编号改变 | 错误参考、判断步骤和搜索关键词 |
用真实字段、旧名称和相关错误码搜索文档仓库。检查共享代码片段、翻译副本和生成参考。共用的行为优先在参考页改清楚,在指南相关步骤中链接到它。
在提交中记录覆盖情况
在 PR 中列出改动的页面、实际验证的版本和仍需跟进的译文。用发布记录与变更集记录对当前用户可见的版本差异。涉及用户必须执行的操作时,在破坏性变更条目中写出判断和迁移条件。