技术文档「覆盖率」指标的分母口径之争：接口级 91.7% / 字段级 70.8% / 场景级 40%，三种口径趋势还会反转——业务方问「文档覆盖率多少」该答哪个？

【背景】 我做了 3 年技术文档，近两年重心在数据分析与指标体系搭建。最近半年在 3 个不同团队做"文档质量"指标落地，反复出现同一个卡点：业务方 / 管理层问"文档覆盖率多少"，我答出来的数字每次都不一样——取决于我用哪种口径，而且三种口径给出的趋势方向甚至互相矛盾。

【现象（带数据）】

1. 一个典型团队：12 个 API 接口，平均 8 个字段（参数 + 返回 + 错误码），20 个典型集成场景（注册、登录、下单、支付、退款、查询……）。

   • 接口级覆盖率：11/12 = 91.7%（写了文档的接口数 / 接口总数）
   • 字段级覆盖率：68/96 = 70.8%（文档覆盖的字段数 / 接口 × 字段总数）
   • 场景级覆盖率：8/20 = 40%（文档覆盖的典型场景数 / 典型场景总数） 三种数字差距 30%+。业务方问"文档覆盖率多少"，我答 91.7% 还是 40%？

2. 更拧巴的：口径切换后趋势会反转。同一个季度、同一批文档改动：

   • 接口级：Q1 91% → Q2 92%（"提升 1 个百分点"）
   • 字段级：Q1 70% → Q2 68%（"下降 2 个百分点"）
   • 场景级：Q1 40% → Q2 55%（"提升 15 个百分点"） 同一批改动，三种口径给出的趋势方向都不一样。

3. 最难的：分母怎么定没共识。

   • 接口级：分母是"接口总数"还是"有流量的接口数"？（有些接口 QPS < 1/min，写了文档也没人看）
   • 字段级：分母是"所有字段"还是"对外字段"？（内部 traceId、内部 debug 参数写了也没用）
   • 场景级：分母是"典型场景"还是"所有可能场景"？（"典型"靠 PM 拍脑袋，换个人拍出来就变）

【已尝试的排查与结果】

• 接口级：最简单，业务方好理解。但"虚高"——一个接口只写了名称和一句话描述也算"覆盖"，实际集成方还是提工单。
• 字段级：最客观，分母可枚举。但"虚低"——有些字段（内部 traceId、内部 debug 参数）写了也没用，反而把覆盖率拉低。
• 场景级：最贴近"文档有没有用"，但"分母怎么定"没共识——"典型场景"靠 PM 拍脑袋，换个人拍出来就变。
• 加权混合：接口级 40% + 字段级 40% + 场景级 20%。听起来合理，但权重 40/40/20 怎么来的？没人说得清。参考站内 id=2246 里"固定权重线性加权在大促日把其他指标全部压到近 0 分"的教训，以及 id=2232 里"线性加权几乎失效"的讨论，我怀疑加权混合在"文档覆盖率"这个场景下也会翻车——三种口径的量程和语义差异太大，线性加权可能只是"看起来合理"。

【期望得到的答案形态】

1. 口径选择：有没有一个"文档覆盖率"的通用口径（接口级 / 字段级 / 场景级 / 还是别的）？业务方问"文档覆盖率多少"，该答哪个？
2. 趋势判断：小样本下（12 个接口 × 8 字段 = 96 个字段、20 个场景）怎么判断"覆盖率提升"是真改进还是噪声？三种口径趋势反转时，该信哪个？
3. 分母共识：接口级 / 字段级 / 场景级的分母怎么定才有共识？"有流量的接口"、"对外字段"、"典型场景"这些限定词怎么量化、怎么避免"换个人拍出来就变"？
4. 权重设计：如果一定要用加权混合（接口级 + 字段级 + 场景级），权重怎么从历史数据反推？有没有可复现的方法（而不是拍 40/40/20）？

【为什么问这个】 文档覆盖率如果全靠"拍脑袋选口径"，业务方看到 91.7% 觉得"文档已经很好了"，实际集成方还在提工单；看到 40% 觉得"文档烂透了"，实际大部分场景已经覆盖。我想把"文档覆盖率"从信仰变成可验证的结论——哪怕只有 12 个接口、20 个场景，也应该有办法用数据把口径定下来、把趋势方向说清楚。