研发团队文档管理工具选型：一次真实的踩坑复盘
2019年，我接手了一家创业公司技术团队的技术运营。第一个让我头疼的问题，不是代码架构，不是人员招聘，是文档。
准确说，是文档的混乱程度，已经开始影响研发效率了。
当时团队二十来个人，文档存在七零八落的地方：NAS里有一份，邮件附件里有一份，有人在Wiki里建了几页，还有人直接在微信文件传输助手发给自己。最夸张的是SRE团队，他们的运维文档存在一台测试服务器的某个目录里，密码换了三任运维才知道这个目录的存在。
文档找不着的痛苦，远大于文档不存在的痛苦。前者会让你以为某个流程没人管，实际上已经有人写了只是你不知道；后者至少让你知道要去解决这个问题。
所以我决定，在招人之前，先把文档管理工具选型这件事做对。
踩过的第一个坑：以为同步就是协同
最初想到的方案很简单——搭一个共享网盘，让大家在同一个文件夹里工作。文件同步了，信息就同步了，协同问题就解决了。
实际运行三个月，问题就暴露出来了。
一个典型场景：后端工程师修改了一份接口文档，Push到共享目录，同时前端工程师也在改同一份文档。两边的修改是独立的，系统只会按时间戳覆盖，后改的那一版会把前一版的改动冲掉。团队里没有人知道哪一版是完整的。
更复杂的问题是版本。图纸改了五版，哪个是最新的？某个功能的设计决策当时是怎么讨论出来的？为什么最后选了方案B而不是方案A？文档本身只呈现结果，不呈现过程。当团队规模超过十个人，这种隐性的上下文丢失开始大量消耗沟通成本。
我后来理解到，文档管理的核心不是"文件在哪里"，而是"谁在什么时间对文档做了什么，以及这个改动对相关人产生了什么影响"。这不是一个同步工具能解决的问题。
踩过的第二个坑：权限管理只分"可见"和"不可见"
选型第二阶段，我开始关注权限管理。
当时的方案是：按项目分文件夹，每个项目成员可以访问自己的项目文件夹，看不到其他项目的内容。这个逻辑听起来合理，实践起来却处处碰壁。
有一次，后端工程师需要调用第三方供应商提供的技术文档，来回沟通了三天——因为那份文档被锁在供应商的文件夹里，工程师没有权限，而管理员是一个外包的运维，不理解这个请求的紧急程度，三天才回复。
还有一次，某个项目的技术方案涉及敏感信息，需要限制查看范围。结果发现系统只能做到"文件夹级"权限控制，一旦开放文件夹，任何人都能把里面的内容复制走。权限颗粒度太粗，实际上等于没有权限管理。
后来我跟同行交流，发现这是一个普遍困境。大多数工具在权限上的设计是：要么全开放，要么全封闭。真正的需求是"谁可以在什么条件下对什么内容做什么操作"——这是一个三维矩阵，不是一个二元开关。
真正好用的权限体系，需要能够定义角色（谁）、操作（能做什么）、资源（对什么）、条件（在什么情况下）这四个维度，并且支持灵活配置，而不是一个固定的权限模板套用所有场景。
踩过的第三个坑：版本管理变成了文件命名比赛
选型第三阶段，我开始关注版本管理。
当时团队的做法是在文件名里加日期和版本号：SRS-V3-20240301.pdf。这种做法管用了一阵子，但随着项目增多、版本增多，文件名越来越长，而且你根本不知道V2和V3之间到底改了什么。
后来有人开始用Git管理文档。这是一个进步——代码的版本管理已经是业界成熟方案，迁移到文档领域理论上也可行。但实践中遇到了新问题：代码的改动是有结构的（函数/文件/提交），文档的改动往往是大量小修改分布在全文各处，而且非技术背景的团队成员不会用Git，普及成本极高。
最终我意识到，版本管理的目标不是"记录历史"，而是"让任何人在任何时间都能回答：当前最新版本是什么？和上一个版本相比改了什么？某一版的完整内容是什么？"这三个问题，如果版本管理工具能让人快速回答，而不是翻半天历史记录，就说明选对了。
三个维度，帮我筛掉了市面上大部分方案
经过三轮踩坑，我总结了三个硬性筛选维度：
第一，同步机制必须是双向可选的。很多工具只支持单向同步（上传到云端或下载到本地），或者强制全量同步。研发团队的实际需求是：我可能只需要同步某些子目录，不需要同步node_modules这类大目录；我可能需要选择性的把本地改动同步上去，但不想让云端所有改动都落下来。这个需求听起来细分，但直接决定了工具在大型项目上的可用性。
第二，权限控制必须有"操作"级别的粒度。能看到和能编辑是两种完全不同的权限，能评论和能删除又是不同的权限。好的权限体系，是把"操作"本身作为权限定义的基本单元，而不是把"文件"或"文件夹"作为基本单元。
第三，版本历史必须有内容级的对比能力。文件列表里显示"今天修改了3个文件"，对实际工作没有帮助。真正有用的是：这两个版本的文档相比，改了哪几个段落？改动的内容占总字数的百分之多少？这需要工具在保存版本时，能够记录文本级的内容差异，而不仅仅是时间戳。
后来我用这三个维度去筛市面上的方案，筛掉了大多数。剩下的一两个，也都各有取舍，没有完美的答案——这本身就是一个取舍题，不是对错题。
选工具这件事，和做架构决策一样，最重要的是知道自己要解决什么问题，以及愿意为此付出什么代价。如果不清楚自己真正的痛点在哪，所有的选型都是盲选。
