4.6 文档与知识指标

概述与动机

本主题以衡量安全维护一个代码库所需的知识是否真正被记录下来、能够被找到，而不只是文档在技术上是否存在于某处，为第4部分收尾。主题 3.5 把沟通与协作当作一个开发者体验方面的关切来讲；本主题从代码一侧探讨同一个底层问题，知识的可获得性：一名新工程师，或一名正在处理陌生代码的现有工程师，是否拥有做出一次安全变更所需的东西，还是这些知识只存在于数量日益减少的资深人员的脑子里。

这里的测量挑战真正艰难，比本书中大多数其他指标都更难，因为文档的质量和有用性天生比一个覆盖率百分比或一个复杂度分数更主观。本主题的方法，是测量有用性的代理指标，而不是存在性：文档实际被访问的频率，尽管已经存在一个文档记录的答案、同一个问题却仍被反复问起的频率，以及一个不熟悉某个系统的人需要多久才能在其中变得有生产力。这些代理指标中没有任何一个单独是完美的，但合在一起，它们给出的图景，比数一个代码库中包含多少维基页面或README文件要诚实得多。

对大团队而言，本主题的关切与组织的任期和人员流动相互叠加，其方式很容易被低估，直到一场危机迫使问题浮现：一个由同样两名工程师维护多年的系统，可以在几乎没有任何书面文档的情况下运转得完全正常，直到那两名工程师在同一年内都离开，这时组织才会发现，那些知识从未真正被以任何持久的形式记录下来。系统寿命通常比初创公司更长、员工连续性也不那么确定的企业和政府组织，比大多数组织更尖锐地承受着这种风险。

核心原则

文档的存在，不等于文档的有用性。 衡量它是否真正有帮助，而不只是它是否存在。
尽管有文档记录的答案存在、问题却被反复问起，揭示的是一个可发现性问题，而不是一个文档投入问题。 更多内容并不总是解决办法。
到达有生产力贡献的入职时间，是整体知识健康状况的一个强有力、实用的代理指标， 直接连接到主题 3.5 的协作指标。
只存在于人们脑子里的知识是一种持久性风险， 而不是一种稳定、可持续的状态，无论它目前运转得多么良好。
文档会衰变。 一年前准确的一个页面，现在可能正在积极地误导人，而这种过时程度本身需要被跟踪。

建议

跟踪文档的访问情况与过时程度，而不只是存在性

在你的文档平台支持的地方，跟踪页面实际被查看的频率，并单独跟踪一个页面自上次更新以来经过了多久，相对于它所描述的底层系统变化了多少（在这里交叉引证主题 4.3 的变动量数据直接有用）。一个描述的系统自上次编辑以来已经发生了实质性变化的页面，很可能正在积极地误导人，而不仅仅是没有帮助，这种过时信号值得获得至少与跟踪文档是否存在同等的关注。

把反复出现的问题当作一个可发现性信号来留意

如果同一个问题在一个团队聊天频道或入职过程中被反复问起，尽管一个记录了答案的文档在技术上存在于某处，这种模式揭示的是一个可发现性问题，答案不在人们自然会去寻找它的地方，而不是一个更多的写作能够解决的文档投入问题。明确地跟踪反复出现的问题，用它们来优先重新组织或更好地呈现现有内容，而不是写更多内容。

测量到达第一次有意义、独立贡献的入职时间

这项指标，在主题 3.5 作为一项协作信号被引入，从代码一侧来看，同样是一项文档与知识健康信号。一个一贯短暂、可预测的入职时间，暗示着真正可获得、准确的知识；一个漫长、高度不稳定的时间，尤其是一个高度依赖具体是哪个人碰巧负责带新团队成员入职的时间，暗示着知识危险地集中在个人记忆中，而不是以持久的书面形式存在。

明确识别并优先处理未被记录的关键知识领域

把你的知识集中度数据（主题 3.5 的巴士因子分析）与文档覆盖情况交叉引证：一个巴士因子为一、又没有任何有意义文档的系统，是一种严重、会累积的风险，理应比一个巴士因子同样低、却有良好文档的系统获得更优先的关注，因为文档至少在培养专门的继任者期间提供了部分缓解。

把文档债务当作你技术债务积压清单中的一个类别来对待

不要单独、非正式地跟踪文档缺口，而要把重大的文档缺口纳入主题 4.5 所述的那份同样可见、量化的积压清单，尤其是对关键的、巴士因子低的系统而言，这样文档工作就能公平地竞争有优先级的产能，而不是作为一项相比以代码为中心的债务补救而言地位更低的任务被永久推迟。

权衡取舍：利与弊

方案	优点	缺点
不测量文档	开销低	知识风险保持不可见，直到一场危机迫使人们发现它
计数文档的存在性（页面数量、README的存在）	简单，容易报告	对有用性、准确性或可发现性只字未提
跟踪访问情况和过时程度	揭示真正的有用性和衰变情况	需要文档平台的分析能力和持续的审阅纪律
入职时间作为代理指标	实用、具体，与真实的业务影响直接挂钩	间接；除文档之外的其他因素也会影响入职速度

核心张力是可测量性与意义之间的张力。文档的存在性微不足道地容易计数，却几乎告诉不了你任何有用的东西；真正的有用性，也就是有人在需要时是否真的能找到并依赖记录下来的知识，才是真正重要的东西，却更难直接测量。解决这种张力的办法，是把本主题所建议的这些代理指标，访问模式、相对于变动量的过时程度、反复出现的问题，以及入职时间，组合起来使用，接受它们单独看都不完美，但它们的汇聚远比单独一个存在性计数更有意义。

与团队讨论的问题

对我们最关键、巴士因子最低的系统而言，是否真的存在有意义、准确的文档，还是一位即将离开的专家会带走大部分真实的知识？ 这是本主题核心关切最尖锐、最具体的版本；先对你风险最高的那个单一系统诚实地回答这个问题。
在我们团队聊天中，有哪个问题尽管在某处存在一个记录了答案的文档，却仍被反复问起？ 如果你能立刻说出一个，那就是一个值得直接修复的可发现性问题，很可能需要重新组织或更好地呈现现有内容，而不是写更多内容。
我们最近一位新团队成员用了多久才做出第一次有意义、独立的贡献，与之前那位团队成员相比如何？ 个人之间巨大、无法解释的差异，往往指向的是高度依赖具体是谁碰巧负责带新人入职的知识，而不是持久、可获得的文档。
我们上一次检查一份文档是否依然准确，相对于底层系统自它被撰写以来变化了多少，是什么时候？ 如果诚实的答案是”我们没有系统性地检查这一点”，那这种过时风险很可能比任何人目前所假定的更大。
我们的技术债务积压清单（主题 4.5）是否包括文档缺口，还是文档工作作为一项相比代码修复而言地位更低的任务被永久推迟？ 检查你实际的积压清单，看看文档债务是可见的、在竞争有优先级的产能，还是实际上不可见的。
如果理解我们最关键、文档记录最少的系统的那一两个人在同一年内离开，我们会付出什么代价？ 这个具体、令人不安的问题值得诚实地回答，而不要把这种风险当作抽象或不太可能发生的事情来对待。

行业视角

初创公司。 对一个知识通过持续、直接的对话传播的小团队而言，正式的文档指标通常没有必要。需要留意的风险，是主题 3.5 所警告的同样那种巴士因子集中，现在专门应用于文档：随着团队成长超过人人每天都在交流的规模，那种非正式运作良好的未记录知识，会变成一种真实的负债。

小型企业。 优先记录你唯一最关键、冗余度最低的系统，哪怕只是非正式地记录，而不是试图在所有事情上都做全面的文档记录。一份简短、准确、涵盖你风险最高的单点故障的文档，比在所有地方都做广泛而浅薄的覆盖，能带来更多真实的价值。

企业。 在这个规模上，文档的过时和可发现性都扩展得很糟糕，因为一个大型组织在许多团队和平台上积累文档的速度，快于任何人能够让它保持最新或一贯有条理的速度。投资于文档平台的分析能力，以在这个规模上跟踪访问情况和过时程度，并把文档债务当作你全组织债务积压清单中的一个一流类别来对待。

政府。 公共部门组织中常见的长期员工任期，可能在表面稳定的背后，掩盖着严重的未记录知识风险，因为一个由同一个人维护了十五年的系统，可能运转得完全正常，直到那个人退休。明确地把文档健康状况当作一项业务连续性关切，直接与人力和继任规划联系起来，而不仅仅是工程上的锦上添花。

案例

企业。 一家金融服务公司在一次不相关的重组过程中发现，其核心风险计算引擎除了少数过时的代码注释之外，没有任何有意义的文档，而最理解它的两名工程师同时被重新分配到了一项新的举措上。一次在巨大时间压力下进行的紧急文档编写工作，在这次重新分配生效之前提取并记录下了关键知识，但这个过程花费了资深工程师数周的专门时间，如果文档健康状况一直被主动地跟踪和优先处理，而不是作为一场紧急情况才被发现，这些时间本可以更渐进、更廉价地分散开来。

政府。 一家州政府一个已有数十年历史的案例管理系统，多年来积累了大量文档，但一次可发现性审计发现，新团队成员一贯找不到相关的现有文档，并在团队频道中反复问起同样那几个问题，而这些问题实际上已经在该机构庞大、组织混乱的文档平台的某处被回答过了。该机构没有选择写更多内容，而是投资于重新组织并改善其现有文档的搜索和导航结构，一次后续调查显示，反复出现的问题出现了可衡量的减少，新员工所报告的入职体验也有意义地更快了，而这一切都没有增加一页新内容。

商业理由：动机、投资回报与总拥有成本

刻意测量和管理文档健康状况的回报，是避免了危机成本：上面的金融服务案例展示了主动、渐进的知识提取，与被计划外人员变动所迫使的昂贵、压缩式紧急工作之间的差异。未被记录的关键知识是一项常设的负债，在它变得非常昂贵之前，其表面上不产生任何可见的成本，而这一切会一次性发生。

总拥有成本主要是跟踪本主题所建议的这些代理指标的纪律，访问模式、过时程度、反复出现的问题、入职时间，以及愿意把文档缺口纳入一份有优先级的积压清单，而不是把它们当作相比以代码为中心的工作永久地位更低的任务来对待。这份纪律的成本，远低于金融服务案例所展示的、作为替代方案的危机模式知识提取。

反模式与陷阱

计数文档的存在性，而不是有用性： 对知识在需要时是否真的能被获取几乎只字未提。
在没有先检查可发现性的情况下，为应对反复出现的问题而写更多内容： 常常完全解决了错误的问题。
从不检查文档相对于系统变化程度的过时情况： 冒着内容积极误导人、已经过时的风险。
把文档债务当作相比代码债务永久地位更低的东西来对待： 让它长期被降低优先级、在积压清单上不可见。
把表面的稳定性（一个多年未变的系统）误当作低风险： 可能在一个只是尚未需要其唯一专家出手的系统背后，掩盖一个严重的、未被记录的巴士因子问题。
只在一场紧急人员变动期间才发现关键的未记录知识： 这正是本主题旨在防止的那种代价高昂、本可避免的失败模式。

成熟度模型

第一级，启动： 文档健康状况不被测量；知识集中度和过时风险只通过危机被发现。
第二级，发展： 存在一些文档，但没有对访问情况、过时程度或可发现性的系统性跟踪。
第三级，标准化： 针对关键系统跟踪访问情况和过时程度，入职时间在全组织范围内作为知识健康状况的代理指标被测量。
第四级，管理： 文档缺口被纳入有优先级的技术债务积压清单，与巴士因子风险交叉引证，以识别出风险最严重的组合。
第五级，协奏： 组织在一次人员变动迫使问题浮现之前，主动识别并解决未被记录的关键知识风险，并能够指出可以追溯到文档投资的、具体的、可衡量的入职或事件响应改善。

讨论思路

我们目前巴士因子低、文档又差的最严重组合是什么？
尽管存在一个记录了答案的文档，哪个问题仍被反复问起？
我们要如何才能知道一份关键文档已经变得过时且具有误导性？
我们的技术债务积压清单是否包括文档缺口，还是它们不可见？
如果我们文档记录最少的系统的唯一专家今年离开，我们会付出什么代价？

要点回顾

衡量有用性，而不是存在性：文档是否真正有帮助，使用像访问模式、过时程度和反复出现的问题这样的代理指标。
尽管有记录的答案存在、问题却被反复问起，揭示的是一个可发现性问题，而不一定是一个内容投入问题。
到达有生产力贡献的入职时间，是整体知识健康状况一个强有力、实用的代理指标。
未被记录的关键知识是一种会累积的风险，尤其是与低巴士因子（主题 3.5）结合时；它在变得代价高昂之前，表面上不产生任何可见成本，而这一切会一次性发生。
把文档缺口纳入你的技术债务积压清单（主题 4.5），这样它们才能公平地竞争有优先级的产能。

参考文献与延伸阅读

Docs for Developers: An Engineer’s Field Guide to Technical Writing，Jared Bhatti、Zachariah Goldberg、Ted Kubaska、Sarah Moir著（面向工程团队的实用文档实践）。
A Philosophy of Software Design，John Ousterhout著（文档、复杂性与可维护性之间的关系）。
Team Topologies，Matthew Skelton、Manuel Pais著（知识集中与分散在组织设计上的影响）。
Accelerate: The Science of Lean Software and DevOps，Nicole Forsgren、Jez Humble、Gene Kim著（文档作为与交付绩效相关的能力之一）。