firefox-ios 三层文档架构 ADR 解读：Confluence、Google Drive 与 GitHub Wiki 的职责划分与协作规范
【免费下载链接】firefox-iosFirefox for iOS项目地址: https://gitcode.com/GitHub_Trending/fi/firefox-ios
导读
本文基于 firefox-ios 仓库中的架构决策记录 ADR-0006：Adopt Three-Tier Documentation Structure 展开，系统讲解该团队如何以 Confluence、Google Drive、GitHub Wiki 三套平台构建可持续的文档治理体系：谁负责长期真相（single source of truth）、谁承载协作探索、谁服务外部贡献者。读完本文，你将理解一套可复制的三层文档结构划分方法、ADR 与文档沉淀之间的衔接流程，以及如何在"内部信息隔离"与"贡献者友好"之间取得平衡。
一、背景：文档碎片化带来的问题
1.1 决策之前的文档分布
在 ADR-0006 提出之前，firefox-ios 团队的文档分散在两个平台：
- Google Drive：同时存放临时协作文档（会议记录、规划草稿）与长期参考文档（流程、工程文档、新人 onboarding 材料），两类生命周期完全不同的内容混在一起；
- GitHub Wiki：承担贡献者相关信息的展示，但缺乏承载持续演进的内部文档与团队知识库的空间。
正如 ADR 的 Context 部分所述，这种碎片化导致难以找到准确、最新的信息——文档分布越散，检索成本越高，文档责任人越不明确，内容越容易过期。
1.2 决策的四大驱动力
ADR 明确列出了影响该决策的主要力量（forces）：
- 长期可维护性与清晰的真相来源（source of truth）；
- 保留 Google Drive用于早期协作场景；
- 通过GitHub Wiki 支持外部贡献者；
- 在保持内部结构清晰的同时，与其他团队有效协作。
这四条力量之间存在张力：内部协作需要灵活开放的草稿空间，而长期维护需要稳定收敛的权威文档；内部知识需要保密，而贡献者文档需要开放可达。三层结构正是对这些张力的回应。
二、决策：三层文档结构的职责划分
ADR 的 Decision 部分给出了完整方案：采用Confluence + Google Drive + GitHub Wiki三层结构，每一层只承担一种核心角色。
2.1 第一层：Confluence —— 终稿与长期知识的唯一真相来源
Confluence 被定位为已定稿、常青（evergreen）文档的家，涵盖：
- 工程概览与架构说明；
- 团队规范（team norms）、onboarding 材料、运营流程；
- 战略性与已定稿的提案；
- 关键外部文档的引用。
判断标准很明确：凡是已经成为长期知识的内容，无论实现指南还是架构更新，都应写入 Confluence。
2.2 第二层：Google Drive —— 探索与协作的工作区
Google Drive 继续保留，但角色被收窄为进行中、探索性、协作性工作的场所：
- 会议记录与协作规划文档；
- 早期提案或设计探索；
- 研究 spike 与技术调研；
- 团队内分享的演示文稿与学习总结；
- 跨团队协作文档。
2.3 决策如何沉淀：从 Drive 到 ADR 再到 Confluence
这是整个文档治理流程最核心的机制，ADR 原文给出了清晰的流转链路：
- 探索阶段：调研、提案、讨论都在 Google Drive 中进行；
- 决策阶段：当调研或提案最终形成技术决策时，负责的工程师在GitHub 仓库中撰写 ADR记录该决策；
- 文档阶段：决策落地后，凡是会成为长期知识的结果性文档（实现指南、架构更新），写入Confluence，并可选择性链接回相关的 Drive 文档作为历史背景。
用 ADR 原文的总结就是：
Google Drive 继续作为探索与发现（exploration and discovery）的家，而 GitHub ADRs 与 Confluence 分别代表决策（decision）与文档（documentation）。
2.4 第三层：GitHub Wiki —— 贡献者赋能
GitHub Wiki 的定位被明确为contributor enablement（贡献者赋能）——帮助新贡献者或外部贡献者完成构建、测试、提交变更的文档，包括：
- 构建与环境配置说明（build and setup instructions）；
- 开发工作流（分支策略、PR 流程、CI 预期）；
- 编码规范与评审指南；
- 如何在本地测试、运行与验证变更。
Wiki 必须满足一个硬性要求：自包含（self-contained）。外部贡献者没有任何内部访问权限，必须仅凭 Wiki 就能顺利参与开发。因此：
- 内部 Confluence 页面只能以名称引用（例如"For Mozilla staff, see the internal Confluence page on Swift Concurrency for more details"）；
- 严禁直接给出内部页面链接，以保证外部贡献者的体验，避免出现死链或权限墙。
2.5 配套清理动作：Drive 瘦身与归档
决策同时包含清理动作：退役并妥善归档 Drive 中过时或冗余的目录（如 Vision-Strategy、Test-Artifacts、Ops-Docs 等），Drive 只保留协作、规划与面试所必需的文件夹。
三、仓库佐证：ADR 机制的实际落地
三层结构中的"决策层"直接落在本仓库的 adr 目录中，这套机制本身就有完整的工程化支撑，可以从源码层面印证 ADR 的运作方式。
3.1 ADR 日志与自动化
adr/README.md 是架构决策日志（Architectural Decision Log），收录了从 ADR-0000 到 ADR-0013 的全部决策记录，包括本篇文章的主题 ADR-0006。该日志由 adr/update-readme.sh 自动维护，脚本内容如下：
#!/bin/sh adr-log -i README.md -e template.md其中adr-log需要通过npm install -g adr-log安装，运行后会把 adr 目录下的各条决策按序写入日志，-e template.md用于排除模板文件本身。这意味着每新增一条 ADR，日志都会自动更新，与 ADR-0006 强调的"可维护性"目标一脉相承。
3.2 ADR 模板：决策文档的书写规范
adr/template.md 定义了标准结构：Status、Context、Decision、Consequences 四段式，并给出了两条重要的书写纪律：
- 全文应控制在一至两页；
- 每一篇 ADR 都要像与未来的开发者对话那样书写，使用完整句子组织成段落，项目符号仅用于视觉风格，不能用来逃避写出完整句子。
这与 ADR-0000（Use Markdown Architectural Decision Records）确立的方法论一致——该条目明确了"一条 ADR 记录一次重要决策""后续 ADR 的 Context 往往来自前一条 ADR 的 Consequences""决策动机对现在和未来的所有人可见"等原则。ADR-0006 正是这套方法的典型应用：它的 Consequences 中提到"迁移需要协调与时间投入"等后续风险，未来若有针对文档迁移的补充决策，很可能会以本文为 Context 继续演进。
3.3 三层结构在当前仓库的映射
从仓库实际内容可以观察三层结构的映射关系：
- Wiki 层（贡献者赋能）：仓库根目录的 README.md 与 CONTRIBUTING.md 承载了构建说明、贡献流程、PR 规范、编码规则（如 SwiftLint 使用、4 空格缩进等），其内容定位与 ADR 对 Wiki 的"自包含、贡献者可独立上手"要求一致；
- 长期工程知识：仓库内的 docs/xcode-upgrade.md（Xcode 升级检查清单）等操作型文档，属于"长期知识沉淀"的典型形态，对应 ADR 中应放入 Confluence 的那一类内容；
- 决策记录：adr 目录下的全部 ADR 文件即"决策层"的仓库内表现。
需要说明的是，Confluence 与 Google Drive 属于团队内部服务，其内容不随仓库分发；仓库内可见的是决策记录与贡献者文档这两层，这也恰好印证了"内部文档不进仓库、仓库文档对外可读"的设计意图。
四、后果分析：收益与成本
4.1 正向收益
ADR 列出了四类正面结果：
- 文档更易于查找与维护；
- 在协作、内部、贡献者三类文档之间建立了清晰边界；
- 减少文档所有权上的冗余与混乱；
- 改善onboarding 体验与跨团队透明度。
4.2 负面与中性成本
同时，决策也承认迁移不是免费的：
- 迁移需要协调一致的努力与时间投入；
- 团队成员需要学习Confluence 的新约定与职责；
- 过渡期间 Drive 与 Confluence 之间可能出现暂时的内容重复。
把这些成本显式写入 ADR，正是模板所要求的"所有后果都应列出，而不只是正向的"——它让后来者知道这套结构不是银弹，而是需要投入维护成本的治理方案。
五、实践启示：如何复用到自己的项目
ADR-0006 给出了一套不依赖具体规模即可套用的文档治理思路，可以总结为四个可操作原则：
- 按文档生命周期分层，而非按平台习惯分层：探索期内容（草稿、会议、调研）与终稿内容（架构、流程）分开存放，探索内容收敛后通过 ADR 固化决策，再升级为长期文档；
- 明确唯一的长期真相来源：终稿文档只在一个权威位置维护，避免"多份副本各改各的"；
- 对外文档必须自包含：凡面向外部贡献者的内容，不得依赖内部系统或内部链接，引用内部资源时只给名称不给地址；
- 定期归档而非无限堆积：对过时目录做显式的退役与归档，保持协作空间的精简。
六、结语
ADR-0006 的价值不在于选择了哪三个具体平台，而在于它用一份结构化的决策记录，把"文档该放在哪里、由谁负责、如何流转"这件常被忽视的工程治理问题变成了可讨论、可追溯、可演进的正式决策。它在探索（Drive）、决策（ADR）、文档（Confluence）、贡献（Wiki）四者之间划出了清晰的边界，也让本仓库的 adr 目录成为观察 Mozilla iOS 团队协作方式的一扇窗口。对于任何正在为文档碎片化苦恼的团队，这份 ADR 都是一份可以直接借鉴的决策范本。
【免费下载链接】firefox-iosFirefox for iOS项目地址: https://gitcode.com/GitHub_Trending/fi/firefox-ios
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
