跳到正文

修订与错误说明

区分文档勘误与用户可见的修复,并记录读者可以采取的恢复操作。

更新受影响的页面

文档里的过期命令、默认值和示例应按适用版本核对。修正单处说明后,检查安装指南、参数表和其他复用该示例的页面。

修复改变了用户可观察的结果时,在对应功能页描述修复后的行为。仍受影响的旧版本可以保留版本提示和有效的临时处理方法。变更记录写清哪个条件下出现什么问题,以及在哪个版本修复。

解释错误和恢复方式

用实际日志中的错误码或关键消息做查找入口。依次说明发生条件、如何确认原因、如何恢复和如何验证恢复结果。一个错误有多个原因时,用各原因特有的诊断信息帮助读者定位。

例如,程序提示 EADDRINUSE 时,可以先确认应用配置的端口是否已被占用,再选择释放端口或修改应用配置。重启后通过实际监听地址验证结果。

记录修复适用的版本

如果 2.1 以前必须手动重建索引,2.1 起保存后会自动生成,就在 2.1 的功能页说明新行为。在需要保留的旧版页面中给出手动步骤。发布条目写清条件与修复后的行为,便于读者确定是否需要升级。

只修正文档错误时,在 PR 中记录核对依据,例如实际的字段默认值、原始版本或能够重跑的命令。更新后按文档影响表查找相关示例。需要编写完整诊断时,可以使用错误与故障排查中的结构。