1. 研发文档治理的痛点与Confluence定位

研发团队几乎都经历过这样的场景：新同学入职第三天，问“接口鉴权规则在哪”，老同事在群里甩出三个链接，一个指向已经停用的旧Wiki，一个指向某人的个人网盘，还有一个是半年前的需求文档，打开后发现里面的字段定义早已和线上代码不一致。文档不是没有，而是“有但不可信”。这正是研发文档治理要解决的核心问题——不是从零开始写文档，而是让文档在正确的位置、以正确的版本、被正确的人维护和使用。

一、研发文档的典型痛点

把研发团队常见的文档问题拆开看，通常集中在五个方面，它们彼此关联，往往同时出现。

1. 散乱：文档没有统一归属。需求写在需求管理工具里，设计稿在网盘，接口说明在代码注释或Swagger，部署手册在某个人的本地Markdown，会议结论在聊天记录。信息本身存在，但入口分散，检索成本极高。一个新人要拼出一张完整的系统图，可能需要翻五个系统、问三个人。

2. 过期：文档与实现脱节。这是最危险的一类问题。代码在迭代，文档停留在某个历史版本。更麻烦的是，过期文档往往没有明显标记，读者无法判断它是否可信。当“文档可能不准”成为共识，团队就会逐渐放弃查文档，转而依赖口头询问，文档体系随之失效。

3. 难查找：检索能力弱。很多团队的文档只按文件夹层级组织，缺少标签、全文检索和交叉引用。知道“大概在哪”的人能翻到，不知道的人只能靠搜索关键词碰运气。文档数量一旦超过几百篇，目录结构本身就成了负担。

4. 权责不清：没人对文档负责。一篇接口文档，产品改了字段、后端改了实现、测试发现了差异，但没有人被明确指定为“这篇文档的维护者”。结果是所有人都可以改，也所有人都可以不改。文档的准确性没有责任人，质量就无法持续。

5. 协作低效：评审与变更没有留痕。文档在群里传来传去，版本靠文件名区分，如“设计_v2_最终_改”。评审意见散落在评论和聊天里，无法追溯某条结论是谁在什么时候确认的。变更发生时，也无法快速定位哪些文档需要同步更新。

二、Confluence在研发文档治理中的定位

Confluence的本质是一个面向团队的协作式知识库，它的核心能力可以概括为：空间（Space）做归属划分，页面树（Page Tree）做结构组织，权限（Permission）做访问控制，版本历史（Version History）做变更留痕，宏与模板（Macro/Template）做内容复用，搜索与标签做检索。这些能力恰好对应上面五类痛点中的“散乱、难查找、权责、协作”四项。

但必须明确Confluence的边界。它不是代码仓库，不替代Git中的README和接口定义文件；它不是需求管理工具，不替代Jira中的需求条目和状态流转；它不是监控或配置中心，不承载运行时数据。Confluence适合承载的是需要被人阅读、讨论、评审并长期维护的说明性知识：架构说明、设计决策记录、接口约定、部署与运维手册、故障复盘、规范与流程。

一个实用的判断标准是：如果一份内容会随代码提交而频繁变化，且需要与代码同版本发布，它更适合放在代码仓库中由代码评审保障；如果一份内容需要跨角色阅读、讨论、达成共识并保留决策过程，它更适合放在Confluence中。两者不是替代关系，而是分工关系。

三、从痛点到治理动作的映射

理解定位之后，落地时可以把每个痛点对应到一组具体动作。下面这张映射表可以直接作为团队自查的起点，左列是现象，右列是Confluence中可执行的动作与判断依据。

四、一个可参考的起步做法

治理不必一次铺开。建议第一个迭代只做三件事：第一，选定一个最痛的研发团队或项目，建立独立Space，把该团队最常用的20篇文档迁入并按页面树整理；第二，为这20篇文档补齐“负责人、最后更新、适用版本”三个字段；第三，约定一条规则——新产生的设计说明和复盘必须写入该Space，不再发到群里。一个迭代后回看：新人提问次数是否下降、文档被打开次数是否上升、是否出现“文档与代码不一致”的反馈。这些信号比文档数量更能说明治理是否有效。