技术文档沉淀的一些思考

开发软件时我们会遇到很多问题，需要基于现有知识做出决策并不断调整，与此同时又创造出了新的知识。这里提到的知识包括需要解决的问题、做出的决策、决策的原因、事实背景以及替代方案等。但研发节奏越来越快，快到我们不可能花费很多时间完整编写、更新文档，但我们又希望获得文档带来的所有好处。如何把技术文档沉淀地更具有性价比就成了一个长期挑战。

1. 概述

从新人指引到功能说明文档，再到各类接口文档，设计文档，运维文档等等，诸如“哪里有文档”，“这些需要问谁”，“文档里写的太老了，还不如直接看代码”之类的对话相信大家都很熟悉。好的知识沉淀无论对研发的效率还是质量都有非常大的帮助，但这件事情要做好却不是件容易的事情。

以往也牵头输出过部门内的各类技术文档，从指引、技术标准规范、最佳实践到产品系统重构设计都有涉及，几年之后再次回顾，就会看到在信息整理，文档输出过程中经常出现的一些问题：

• 文档构建成本高
  往往需要的系统已经开发完了，再回头补充相关文档；另一个场景就是新人接触系统的时候，一边学习一边补充更新相关文档。
• 文档腐化严重
  由于系统在不断迭代，研发模式也在追求更敏捷，更快速。这就更加使得文档迭代速度和现实系统迭代速度之间的矛盾进一步加深，文档上的信息会一步步落后于系统，很多小变更累积起来的时候会发现原本文档中的信息已经不可信，导致阅读者最终不再使用文档。
• 文档受众不明晰
  不少文档都是按编写者自己的思路书写，充斥着各类“专业术语”，省略了很多“前提假设”。虽然看着产出了不少文档，但当其他人使用时依然感觉文档里的信息不全。
• 文档使用不便
  虽然现在基本上文档系统都会有全文检索机制，但各职能文档分散，并且组织架构会变更，项目和系统维度不一致，文档容易碎片化，阅读时无法了解整体概况；文档系统也会根据现实情况迭代变化，导致信息冗余或者缺失。此外，文档和代码、配置等具体实现分离，也增加了信息关联的难度。

2. 案例

先举4个过去实践过的案例：

• 第一个案例是个效果未达预期的案例：原本部门用过几个知识库平台，但由于各种原因（功能陈旧、版权付费等）都废弃了。
  为了能够确保文档不会因为知识库变更导致缺失，就自研了一个wiki平台，引入markdown编辑器，期望能够通过更简单的文本语法、全文检索、符合部门需求的权限管控，以及文档导入导出等功能，帮助大家构建完整的文档库，提升信息留存、最好知识沉淀。
  最初确实看起来很好，各种文档都丰富了起来，但一段时间后，文档腐化，搜索偏差，信息碎片化，信息不准确等等问题又都冒了出来，然后逐渐地这个平台上的文档也越来越陈旧，使用的人也越来越少，上面很多的文档都逐渐地“死去”。
  它失败的点可以归结为：单纯工具思路，并没有在文档编写、腐化防护、知识使用这几个核心点上有关键性改变。所以最终只是有了一个更好用的编辑平台，但同时也容易被更好用的编辑平台轻松替代，无法在文档沉淀上发挥更大的作用。
• 第二个案例的效果比较好：严选接口管理平台。
  接口需要文档记录这是一个强需求。在立项做这个平台的时候，其实原先就有文档方式（有纯线下文档，也有wiki之类在线文档等各类形式），内部也有NEI平台，但核心逻辑都是先产出文档，再根据文档构建代码，更关注研发初期阶段。接口描述和代码的一致性完全依赖研发流程的规范和执行者意识，和线上版本的关联非常不易。
  而严选接口管理平台从一开始就更偏重在应用的长期运营和迭代阶段，采用的核心逻辑在于根据代码扫描自动构建接口列表，从而确保接口列表和现实代码是完全一致的，并结合自动抓取的git分支信息，可以有效关联不同版本下的接口具体信息。虽然从平台本身来讲受限于投入的资源有限，功能丰富度和易用性方面还有很大的提升空间，但它依然可以成为让使用者都放心的信息查询源，无需线下咨询确认，就能清晰地获取到和源码一致的各版本接口详情。
  它的成功点总结为：核心解决了以往接口类文档中文档腐化和定位信息不便的两个问题。
• 第三个案例的结果同样未达预期：由于接口管理平台运作比较有效，就想着沿用类似的思路，依靠业务中台的技术演进思路，把领域概念的注解方式引入到研发工程中，期望能够把核心业务规则、活动、场景等依托平台做有效沉淀。
  但现实是这块做着做着更多变成了另一个形态的接口管理平台。虽然后期尝试加入了产品需求文档功能，但依然没有做到技术和产品实现的关联。
  这个案例的问题原因可以总结为：受众不明晰，期望兼顾各方，但在各方尚未做到“语言一致性”前，并且也没有在前置知识普及这方面有明确措施和手段之前，单纯靠个体意识和工具是无法做好业务整体流程（往往跨应用）下的知识关联。
• 第四个案例从结果看还是不错的：我们依托办公IM中现成的机器人服务台机制，构建渠道侧的SOP知识库。当知识库构建完毕后，很多情况下提问方就可以自行查询服务台获取答案，减少技术人员以往的回复精力。
  为了让服务台使用频率越高，SOP知识库沉淀的过程中信息记录也会更站在使用者的角度行文，对整个知识库的及时更新也会更有动力，从而达到正反馈循环。
  它的成功点归结为：文档受众明晰和使用场景明确，从而能让知识更有效地传递到所需的对象。

根据这些过往案例，对于技术文档做好有效沉淀，归结了以下几个我认为的关键经验教训：

• 知识沉淀是为了知识能够被再次使用（至少是预期），所以不会被再次使用的文档，其实也没有被编写的必要，避免为了文档而文档。
• 确保文档的新鲜度以及和现实的一致性是第一位，否则使用文档就会带来额外的纠偏成本，自然会越来越少地被使用到，最终将不再被使用。
• 知识记录需要区分受众，如果是受众较广的，那么要么确保团队已经达成了“语言一致性”（即已经有相同的背景知识），要么就区分受众记录不同角度的知识。否则在知识沉淀的价值上就无法达到预期，表现出来的往往是看着写了很全面的文档，但真正被使用的却很少，依然存在很多线下咨询、问答的场景。

• 工具需要为明确的知识沉淀方式服务，如果本身知识沉淀的方式就不是最有效的路径，工具再好用也无法达到目的。

3. “活文档”

那么如何记录知识，或者说怎么样创建文档才能更高效，更有价值。最近读完《活文档：与代码共同演进》一书后，发现作者对于文档这块的见解还是很符合个人在这方面的理解。

先解释下这里的几个名词：

• 知识增强：用缺失的知识丰富（或增强）系统本身。

• 固有文档：已存在于系统中的知识（例如：代码）。

• 现成的文档：被广泛理解、权威性、标准性的现有知识。

• 知识开发：梳理系统内纷乱的信息，确定权威来源，整合散落的记录，提炼成有价值的知识。

• 集成的文档：系统研发过程中工具提供的辅助信息（例如：IDE里的方法列表提示）。

• 已发布的快照：生成只读性文档（表现方式往往会携带文档的版本号)。

该书作者认为编写文档的目的是“将有价值的知识传递给当前以及未来的人”，所以知识传播才是本质。传统文档只是知识的一种转录方式，既然是转录就会带来额外成本和损耗。而大部分知识是已经存在于事物中的，所以应该采用知识增强的方式，尽可能让系统内的知识完整，同时让知识易于访问来更有效地传递准确、有价值的知识。

在区分了不同知识的稳定性情况后，对于一直在演进的知识，“活文档”的理念是把系统中的知识尽可能完善（提升准确性、避免腐化、减少知识冗余），然后再充分利用各类工具，把系统中的知识按照最有利于使用的方式自动化地转录到相匹配的载体/形态上。

“活文档”的沉淀思路，简而言之就是：识别出有价值的知识，找到它当前的位置，并确定可能缺失的知识以及变更的频率，通过知识增强、知识开发等方式以最小的代价获得最大的收益。

4. 后继

结合原本案例的总结，严选团队的研发流程和习惯，以及“活文档”一书中的思想，针对技术“文档”沉淀有了一些更具体的实践思路，后继的改进会从以下几个方面着手尝试技术文档的沉淀方式：

• 稳定性知识的完善
  当下的核心关键点在于尽量靠近系统本身，确保知识和现实的关联度更为直观。准备引入决策日志（ADR）机制，确保重大设计中的决策信息能够被按照统一的方式持久化，并和源码一起保留在工程的git库中，内容包含以下几个要点（格式参考Nygard format）：状态、背景、决策、结果。作为高层设计文档和具体工程实现之间的关联补充。
• 固有知识的丰富和补充
• 目前严选的接口管理平台依然是java为主，nodejs有一部分有限的支持，所以下一步的重点核心还是完善nodejs的支持力度。同时关注golang使用的范围，考虑增加对golang工程的支持。
• 知识开发的尝试
  切入点是编码规范的沉淀方式变化：
• 当前现状是仅用文本化的技术规范，然后依靠技术规范对开发者进行意识上的宣贯，并提供相应工具辅助执行或者作为约束，规范权威来源仅有一份文本化的文档。
• 实践的方案会采用sonar的静态扫描规则库作为后继的编码规范权威来源之一，将编码规范的制订从原本的先文档再检查改为先检查再自动文档化。即利用工具自动把sonar的规则库转成可读的文档，每次规则库的变更都会自动更新文档，从而确保规范的事实要求和文档保持一致。
• 集成文档的探索
  指引类知识（例如工作环境创建等）沿用办公IM自动化服务台的方式，把指引知识库和服务台连通，方便使用者利用工作IM，可以更方便、准确地找到问题，避免记忆分类规则、按目录一一个个去查找。

对于技术文档的沉淀，不能把关注点仅仅停留在写了多少文档，格式是如何的，目录是怎样组织分类的，文档存放在哪里等方面。这些都已默认假定了文本化才是知识沉淀的唯一表现。

我们期望的是通过上述的实践思路，跳出单纯文档化，找出更有性价比的沉淀方法，把“有价值的知识传递给当前以及未来的人”这件事做得更好。

本文由作者授权严选技术团队发布