firefox-ios 三层文档架构 ADR 解读Confluence、Google Drive 与 GitHub Wiki 的职责划分与协作规范【免费下载链接】firefox-iosFirefox for iOS项目地址: https://gitcode.com/GitHub_Trending/fi/firefox-ios导读本文基于 firefox-ios 仓库中的架构决策记录 ADR-0006Adopt 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-0000Use 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.mdXcode 升级检查清单等操作型文档属于长期知识沉淀的典型形态对应 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），仅供参考 firefox-ios 三层文档架构 ADR 解读：Confluence、Google Drive 与 GitHub Wiki 的职责划分与协作规范
firefox-ios 三层文档架构 ADR 解读Confluence、Google Drive 与 GitHub Wiki 的职责划分与协作规范【免费下载链接】firefox-iosFirefox for iOS项目地址: https://gitcode.com/GitHub_Trending/fi/firefox-ios导读本文基于 firefox-ios 仓库中的架构决策记录 ADR-0006Adopt 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-0000Use 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.mdXcode 升级检查清单等操作型文档属于长期知识沉淀的典型形态对应 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），仅供参考