documentation-review.md

文档校对与维护流程

为确保文档与功能演进保持一致，建议在每次迭代中遵循以下流程：

1. 变更识别

1. 在创建功能分支时，列出可能影响文档的改动（接口、配置、部署方式等）。
2. 将受影响的文档放入 Issue / PR 描述的 checklist，确保评审时可见。

2. 同步更新

1. 代码先行草拟：在实现过程中随手记录关键行为变化，以免遗忘细节。
2. 更新对应文档：
   • 架构变化 → docs/architecture.md
   • API 行为 / 字段调整 → docs/api/
   • 脚本与实操示例 → README.md、examples/
   • 运维与部署 → docs/deployment.md
3. 对于需要插图的场景，优先使用 Mermaid，以便后续版本控制。

3. 同伴校对

1. 提交 PR 时，指派至少一位维护者校对文档。建议按以下 checklist 进行：
   • 术语统一（Agent、任务、链上快照等）。
   • 中英文混排时标点一致，数字与单位之间保留空格。
   • 示例命令可直接复制运行，无缺失参数。
   • 图片或流程图在 Markdown 中可正常渲染。
2. 校对者完成审阅后，在 PR 中留下确认评论，记录潜在改进项。

4. 发布前验证

1. 使用 go test ./...、go build ./... 或示例脚本验证文档中的命令。
2. 若文档涉及外部依赖（如 RPC 节点），需在发布说明中明确前置条件。
3. 生成发行说明时，链接到更新过的文档片段，方便读者查阅。

5. 定期维护

• 每个版本至少安排一次文档巡检，检查链接失效、示例过期等问题。
• 将文档维护纳入 OKR 或迭代验收标准，避免“代码已更新但文档缺失”的情况。
• 对于废弃功能，及时标注弃用计划，并在 README 与 API 文档中添加迁移提示。

该流程可根据团队规模与发布节奏做适当调整，但建议始终保留“同步更新 + 同伴校对 + 发布验证”三大环节。