让读者用观察结果找到页面
以实际错误码或消息中的稳定短语作为标题或开头。日志中的项目路径、时间和请求编号可用示例值。写明消息出现在哪里,例如终端、构建日志或浏览器界面,并交代适用的版本和模式。
错误码可能对应多个原因。先给读者一个成本较低的检查,再根据观察结果分流。确认原因后提供恢复步骤与验证方法。
用现象、检查和动作编排诊断
示例工具提示 INDEX_FILE_MISSING 时,可以按下表定位。
| 实际现象 | 先检查 | 恢复动作 |
|---|---|---|
| 构建结束后找不到索引 | 输出目录是否与配置一致 | 从配置指定的目录读取产物 |
| 部署后搜索为空 | 已部署资源中是否包含索引 | 添加索引产物后重新部署 |
| 项目移动后首次构建失败 | 日志中的索引输入路径是否仍存在 | 更新相对路径并重新构建 |
每行使用能验证的条件。读者完成恢复后,写明希望看到的状态,例如搜索返回示例文档,并报告索引文件的实际读取位置。
交代重试、回退和报告途径
重试会改变数据或产生重复任务时,说明在重试前怎么判断上次是否成功。回退要注明适用的版本和数据条件。需要上报时,告诉读者应收集哪些版本、错误字段和最小输入,再按可复查的问题报告组织信息。
维护错误参考时,用对应版本重新触发一次错误,并确认恢复步骤能消除错误。跨版本变更可以按修订记录保留旧错误名或替代操作。