研发效能|AI时代的文档策略演变:为什么集中式知识库成为企业必备-夜雨聆风

研发效能|AI时代的文档策略演变:为什么集中式知识库成为企业必备

整理编辑｜TesterHome社区

信息来源｜Grab工程博客

作者｜Karen Kue 、Athar Hameed

Preeti Karkera、Anna Ooi

在当今快速发展的技术环境中，文档不再仅仅是代码的附属品，而是工程团队成功的关键支柱。当东南亚领先的超级应用Grab面临文档管理困境——从散落各处的Google文档、Wiki页面到版本混乱的技术手册——他们开启了一场静默的革命。这场革命不是关于抛弃工程师喜爱的工具，而是关于重新思考如何让知识真正流动起来。

从最初的”文档即代码”理念到最终采用集中式知识库，Grab的探索揭示了一个深刻的真理：在规模扩展时，组织需要的不仅是更好的工具，更需要更智能的知识架构。当工程师在紧急事件中因为找不到正确的操作手册而手忙脚乱，当新成员在入职第一周就迷失在文档迷宫中，当AI助手因为知识碎片化而给出错误建议——这些问题的答案不在更多的文档中，而在更聪明的组织方式里。

本文将带您深入Grab的文档进化历程，探索他们如何在保持工程师自主权的同时，构建一个让知识触手可及、质量可控、未来可期的文档生态系统。

以下为作者观点：

大家好，首先说说Grab文档的演进历程。

2021年初，Grab采用了Docs-as-Code（文档即代码）方法来解决我们技术文档流程中的空白，正如我们在博客文章《拥抱文档即代码》中所述。受到其他市场领导者的实践启发，我们将文档集成到工程师的工作流程中，使其成为代码库的一部分。

这种方法通过为工程师创建一个单一的事实来源来搜索和构建知识，解决了我们最初的文档挑战，使文档维护成为必要而不再是事后考虑。在使用四年之后，我们过渡到了集中式文档存储库。这一变化并非要放弃Docs-as-Code，而是为了适应新的和不断增长的组织需求。

下文将详细阐述这一旅程中每个阶段的动机、收益和经验教训，展示我们的文档策略是如何演变的。

什么是Docs-as-Code？

Docs-as-Code是一种使用工程师用于源代码的相同工具和工作流程来管理文档的方法。内容以纯文本Markdown格式编写，可以使用任何代码编辑器轻松编辑。Markdown是一种轻量级标记语言，使用简单、可读的符号（如#表示标题，*表示列表）来格式化文本，并可以渲染为HTML和其他输出格式。它存在于版本控制存储库（如GitLab）中，因此文档与代码一起演变。更新需要经过相同的合并请求审查和自动化的CI/CD检查。

这种集成模型使Grab的团队能够将构建、测试和发布文档作为管道的一部分。然后，我们通过集中式的内部开发者门户展示这些文档，以便更容易发现，并实施治理以确保质量。

我们的理想使用场景

想象一位工程师负责维护其团队管理的产品或平台的文档。这位工程师在Markdown中创建全面的文档，包含诸如概述、入门指南、操作指南、故障排除、常见问题解答以及特定平台的相关参考等内容。文档包含在合并请求中，并在代码合并后立即发布到文档门户上。这种无缝集成培养了工程师对文档的所有权意识。然而，虽然这种场景很理想，但在实际实施中却面临着重大挑战。

我们用Docs-as-Code解决的问题

在采用Docs-as-Code模型之前，文档通常分散在Google文档、幻灯片、wiki和临时文本文件中，这导致了版本混乱、可发现性差以及质量保证方面的空白。将文档集中到版本控制存储库中，与代码并存，创建了一个单一的事实来源，将更新与相同的拉取/合并请求审查绑定，并启用了自动检查，如链接验证、样式检查和预览构建。

行业实践反映了这一转变：Kubernetes在其网站上以Markdown格式维护文档，使用GitHub作为存储库，并使用Hugo构建网站，鼓励在功能开发的同时更新文档。

当文档与代码嵌入并流经相同的CI/CD管道时，工程师更有可能在代码更改的同时更新文档。这种方法默认情况下使内容保持最新并与发布同步。TechDocs团队还可以设置标准化指标，以维护所有文档的质量，并实施质量门禁和阻止机制，确保每个文档都符合质量标准。

分散式存储库的局限性

随着Grab工程足迹的扩大，我们分散式的Docs-as-Code方法开始在规模上承受压力，出现了使文档更难发现、维护和自信交付的摩擦。

碎片化的用户体验和不均衡的标准

当文档分散在多个存储库中并由团队独立管理时，信息架构、语调、术语和粒度都会出现差异。相似的概念最终有了不同的名称，页面遵循不一致的导航和模板，冗余或不一致的指导大量出现。

最终，搜索体验变得嘈杂且不可靠，因为多个版本的”真相”浮现出来。其影响表现为更长的入职时间、更多的技术支持升级、当不同团队的操作手册不同时事件响应变慢，以及信任度逐渐下降，最终推动人们转向部落知识。

对于TechDocs团队来说，分散化使得强制执行标准模板、格式和质量门禁变得困难。文档分散在许多存储库中，每个存储库都有不同或没有检查器、CI设置和约定，运行组织范围的自动化（检查器、链接检查器、可读性检查）或应用统一审查步骤变得不可靠。这导致监督有限和持续的不一致性，降低了用户体验和对文档的信任。

难以跟上步伐和保持可发现性

快速发展的平台意味着分散式文档老化迅速且难以找到。频繁的基础设施和框架发布引入了破坏性更改和弃用。团队难以及时了解情况，导致错失优化机会，并因过时的做法而带来潜在的安全风险。

同时，随着内容分散在多个存储库中，管理和跟踪内容对负责TechDocs的团队来说变得越来越具有挑战性。当团队更改其源存储库的位置时，他们通常未能通知管理团队，这使得跟踪更新和新的位置变得困难。这种缺乏协调在发现相关文档和维护集中记录方面造成了重大障碍，最终影响了生产力并延迟了决策制定。

为什么我们转向集中式存储库

集中式存储库使我们能够解决这些扩展挑战，同时保留Docs-as-Code的好处：

AI驱动的增强功能

我们不再只为人类工程师编写文档。随着我们将更多AI工具集成到开发者体验中，我们的文档也作为内部代理的知识库。集中式、基于Markdown的格式为代理提供了干净、可读的内容，位于一个位置，这支持更好的集成、更快的理解和更准确的响应。

改进的质量保证

集中我们的文档使管理团队能够跨所有内容运行自动检查器进行质量检查。这有助于确保一致的标准，减少人工监督，最大限度地降低错误风险。贡献者还被要求为每种文档类型使用适当的模板，确保默认情况下具有一致的结构。

统一的搜索体验

统一的搜索体验改变了工程师访问信息的方式。他们可以搜索任何主题并找到相关文档，而无需导航多个存储库。全局搜索覆盖层结合了两种方法：用于快速导航的模糊页面标题搜索，以及跨所有TechDocs内容的Glean驱动搜索。Glean是一个企业搜索和AI助手平台，与内部工具集成，帮助用户更高效地查找和使用信息。这种搜索功能节省了时间，帮助工程师保持信息灵通。

简化的贡献流程

虽然分散式模型允许工程师使用GitLab Web IDE、本地编辑器和GitLab CLI命令进行快速更新，但向集中式系统的过渡通过提供一致的编辑环境帮助简化了这一过程。即使使用这些高级工具，集中式存储库也为所有文档提供了一个统一的位置，减少了需要跨多个存储库导航的需求。

集中化还为TechDocs团队提供了对文档行为和健康的更清晰可见性。实施集中式存储库后，团队提取了用户活动的统计数据：大约每50分钟就有一个新更新被合并，每天大约有27次提交，大约63%的更改是小型到中型的改进。这些信号表明文档维护正在进行中，频繁的微调修复了拼写错误、澄清了步骤，并保持指导最新，而不是偶尔的批量更新。下图说明了Grab员工如何在实践中使用集中式存储库。

对演变的反思

这一过渡并非没有障碍。为了弥补分散式Docs-as-Code工作流程留下的空白，我们实施了：

自动同步：我们将关键内容从服务和平台存储库同步到中央中心，以防止出现空白，同时保持重叠期短暂，以避免两个事实来源和在旧存储库退役时错过更新。
培训课程：我们举办了实践研讨会，帮助工程师导航新平台并了解其好处。
持续反馈：我们设置了调查和定期检查，根据实际使用情况改进工具和流程。

结论：选择适合你们的方法

具有分散式和集中式存储库的Docs-as-Code并非相互排斥；它们在不同背景下表现出色，并且可以结合使用。当工程师是主要贡献者且文档自然随代码交付时，分散式编写效果很好。当您优化组织范围的可发现性、一致性、治理和分析时，集中化变得有价值。我们从向集中式Docs-as-Code存储库的转变中得出以下结论：

在团队需要自主权且文档与服务紧密耦合时，使用分散式Docs-as-Code。

当您需要单一事实来源以进行发现、标准化模板和样式、一致的CI检查、所有权元数据以及更清晰的合规性和审查门禁时，使用集中式存储库。

考虑混合方法：作者在服务存储库中创建文档，并使用共享模板、所有权元数据、自动质量检查以及集中式发现和治理发布到中央门户。

在Grab，分散式Docs-as-Code在早期培养了强烈的所有权意识。随着我们的扩展和受众的扩大，集中式存储库和统一的发现界面变得至关重要，以保持一致性、提高可查找性并支持多样化的用户需求。文档策略随着组织而演变。目标不是永远选择一种模型，而是认识到转变的信号并进行适应，以便工程师能够在正确的时间可靠地找到正确的信息。

Grab工程博客文章链接：https://engineering.grab.com/evolving-documentation-strategy

MTSC2026中国互联网测试开发大会

将于8月15日在深圳举行