跳到正文

判断文档更新范围

从用户可观察的行为出发,确定一次代码改动需要更新哪些指南、参考和版本说明。

先找对读者有影响的行为

对照改动前后的测试、类型、默认值和界面,记录读者在什么条件下看到什么变化。调整标题搜索排序时,核对结果顺序和案例。变量更名且仍兼容旧值时,更新首选写法并说明兼容边界。

能通过文档判断的事情包括引入版本、可用平台、启用方式、默认值、优先级、输出结构和错误。代码整理只涉及内部实现时,可以验证现有示例是否继续成立。需要跨版本发布时,确认要更新的是稳定版、下一版本还是两者。

顺着使用路径检查页面

改动优先检查的文档
新增参数或公开函数API 或配置参考、调用示例、安装或接入指南
用户可见的修复受影响的故障排查、示例输出、版本说明
启用方式或默认值改变首次使用步骤、配置参考、升级指南
删除字段或旧行为迁移条目、弃用提示、引用该字段的旧示例
报错条件或编号改变错误参考、判断步骤和搜索关键词

用真实字段、旧名称和相关错误码搜索文档仓库。检查共享代码片段、翻译副本和生成参考。共用的行为优先在参考页改清楚,在指南相关步骤中链接到它。

在提交中记录覆盖情况

在 PR 中列出改动的页面、实际验证的版本和仍需跟进的译文。用发布记录与变更集记录对当前用户可见的版本差异。涉及用户必须执行的操作时,在破坏性变更条目中写出判断和迁移条件。