区分弃用、计划移除和已移除
把状态写到旧功能仍会被读者找到的位置,例如参数表、错误页或教程。注明何时开始弃用、现有调用是否继续工作、替代写法从哪个版本可用。已经确定移除版本时给出该版本。排期尚未确定时,描述当前支持状态和已知信息。
| 状态 | 可以写清的信息 |
|---|---|
| 已弃用,仍可使用 | 自 1.8 起弃用,仍可读取 indexFile,新项目可改用 search.output |
| 已确定移除版本 | 从 2.0 起需要迁移到 search.output |
| 已移除 | 2.x 读取 search.output,旧配置可按迁移条目更新 |
示例中的版本和字段用于说明写法。实际文档应对照发布说明、运行时警告和测试记录。
给出可验证的替代步骤
提供最小替代示例。新能力有适用范围时,说明旧功能使用者需要额外检查的行为。迁移后用用户能看到的状态确认成功,并在升级指南记录版本次序。
保留读者正在使用的入口
页面更名或合并前列出旧路径、旧锚点和当前引用。将旧页面引向用途相同的新页面,兼顾版本和语言。需要按标题定位时,同时验证重定向后的片段地址。无法迁移到对应段落时,旧入口应说明内容的新位置或历史版本的查阅方式。
发布后打开常用的旧地址,确认没有跳到无关功能,并更新站内链接以便后续维护。