每条长期事实只由一处维护
One Canonical Owner per Documentation Fact
把事实分配给一个明确的文档位置,其他页面通过引用复用。
以下示例与示意结果由本站编写,用于说明方法,不是模型实测结果。
使用场景
README、架构图和周报重复写认证迁移状态,三处分别说完成、阻塞和进行中。教学项目已有 STATUS.md 负责当前状态、ARCHITECTURE.md 负责结构、DECISIONS.md 记录决定。需要先核实真实状态,再让读者知道一项事实由哪处维护。
具体做法
按文档职责为事实确定唯一维护位置:当前阻碍归状态,模块位置归结构,重要取舍归决定。其他页面链接权威记录,不各自维护独立当前值;受众确需摘要时注明来源和观察时间。更新一项事实后,检查派生说明没有冒充另一个权威副本。
反例
只把 README 的迁移状态改成完成,架构图继续写阻塞,周报维持进行中。三处都声称是最新记录。
改进写法
核实认证迁移的实际状态后,在 STATUS.md 维护当前进度与阻碍;ARCHITECTURE.md 保留模块位置和结构规则;DECISIONS.md 保留取舍历史。README 链接这些职责明确的记录。需要周报摘要时标明从 STATUS.md 得到的观察时间,不让三处各自定义当前状态。检查现存差异并修正派生说明。
为什么这样改
重复副本会独立过期,读者无法知道哪个值支配下一行动。事实归属与可追溯引用让更新集中在维护位置,其他文档可以服务不同读者而不争夺同一个当前结论。
如何验证
示意核实状态若为“等待接口验收”,STATUS.md 写该状态,README 链接它;架构图没有另一份完成结论。周报如需摘要,附观察日期与状态来源。
从概览追踪每项事实,应能到达一个明确的维护位置。链接断裂、派生摘要无来源或三处互相矛盾,都需处理。
适用边界
唯一维护位置不意味着不做备份,也不禁止带时间的历史记录。权威记录本身仍需事实核对;长说明、历史和当前状态有不同用途,不必强行用来源中的固定文件名。
原文与版本
- affaan-m/ECC · Document roles
查看此版本的文件ef648e01899b - affaan-m/ECC · Capture private and team knowledge in their existing authoritative locations without duplication
查看此版本的文件ef648e01899b