Add [Documentation] Proposed documentation ADR

[Cramsden]

💡 Description

Proposal for new documentation structure

🎥 Demos

Documentation Policy


To clarify where different types of documentation live across our tools: Confluence, Google Drive, and the GitHub Wiki.

Confluence — The Source of Truth

Use for:
Long-term, finalized documentation that represents how we work and what we know.
Examples:

• Architecture & system overviews
• Process documentation (incidents, releases, onboarding)
• Team norms, agreements, and meeting cadences
• Strategic or finalized proposals
• Engineering deep-dives (e.g., Swift Concurrency, Security, Logging)
  Notes:
• Each page should have a clear owner and date of last update.
• Finalized Drive docs (e.g., proposals) are promoted here.

Google Drive — Collaboration & In-Progress Work

Use for:
Drafts, meeting notes, planning docs, and any document still under discussion or requiring frequent collaboration.

Sub-sections:

Team-Meetings

• Meeting notes, sync summaries, action items.

Planning

• Sprint, quarterly, and OKR planning docs.

Interviewing

• Interview processes, templates, and schedules.

Cross-Team Collaboration

• Shared proposals or working docs involving other teams.
• Examples:
  • Product feature proposals under review
  • Design collaboration docs
  • Platform integration discussions
• Archive quarterly (e.g., Archive/2025-Q1)
• Once finalized → move to Confluence.

GitHub Wiki — Contributor & Repository Docs

Use for:
Information external contributors or new engineers need to build, test, or contribute to our project.
Examples:

• Build/setup instructions
• Repo structure and branch conventions
• Contribution and PR guidelines
• CI/testing workflows
• How-tos specific to codebase (e.g., feature flags, Redux setup)
  Notes:
• Keep concise and technical; no internal planning or process docs.

Archiving and Maintenance

• Retire old Drive folders into /Archive every quarter.
• Confluence pages should include “Last Reviewed” metadata.
• Add a brief “Doc Review” item to team retros every month.

Type of Doc	Tool	Example
Meeting notes	Google Drive	“iOS Team Sync 2025-11-04”
Proposal draft (cross-team)	Google Drive / Cross-Team Collaboration	“2025-01 TabManager Proposal”
Finalized process	Confluence	“Incident Response Process”
Contributor guide	GitHub Wiki	“How to Build Firefox iOS”
Architecture overview	Confluence	“Swift Concurrency Model”
Archived / retired docs	Drive → Archive	“2021 Q4 Retros”

📝 Checklist

• I filled in the ticket numbers and a description of my work
• I updated the PR name to follow our PR naming guidelines
• I ensured unit tests pass and wrote tests for new code
• If working on UI, I checked and implemented accessibility (Dynamic Text and VoiceOver)
• If adding telemetry, I read the data stewardship requirements and will request a data review
• If adding or modifying strings, I read the guidelines and will request a string review from l10n
• If needed, I updated documentation and added comments to complex code

[ih-codes]

Sounds good to me! 👍 Just a few thoughts.

Have you explored how we can get our own Confluence directory set up at Mozilla for the iOS team? 👀 I'm eager to give it a try but of course it might be closer to Christmas when things have slowed down a bit...

[ih-codes]

I think most meeting notes make perfect sense to be in the team folder, but there may be some more sensitive 1:1 notes that should remain in personal folders with only the 2 parties involved.

[ih-codes]

Another pro: confluence tagging and searchability should improve discoverability of documentation as well, especially compared to the GitHub Wiki!

[lmarceau]

We should adapt the adr/README as well

[Cramsden]

@ih-codes we already have a team confluence page. It is just very out of date and would need to be cleaned up. https://mozilla-hub.atlassian.net/wiki/spaces/Mobile/pages/21955148/Firefox+for+iOS

[cyndichin]

thanks for proposing this @Cramsden !! looks great, we used Confluence back when I was in Pocket so happy that we're bringing this here. I had one comment for clarity, but doesn't block this PR :)

[cyndichin]

Would these also benefit to add to our wiki? It seems that our contributors can benefit from understanding our architecture. What about feature specific documentation (i.e requirements, architecture, figma design)?

[Cramsden]

@cyndichin I think the idea here is that you need some information on how to build a feature using the app's architecture in order to contribute but you don't necessarily need to do a deep dive in order to contribute and that sometimes too much information can be overwhelming/turn folks off of contributing. I think the idea is that we put in the wiki what we know contributors need and if there is any documentation they are missing we can learn from that and add it in. I suspect it will be a lot less than we think

[cyndichin]

Makes sense! Thanks for clearing it up, appreciate this ❤️

[cyndichin]

nice 🔥

[ih-codes]

Will approve, just a few formatting nitpicks before merging though!

[ih-codes]

Suggested change

	- Meeting notes and collaborative planning documents
	- Early-stage proposals or design explorations
	- Research spikes and technical investigations
	- Presentations and learning summaries shared within the team
	- Cross-team collaboration documents
	- Meeting notes and collaborative planning documents
	- Early-stage proposals or design explorations
	- Research spikes and technical investigations
	- Presentations and learning summaries shared within the team
	- Cross-team collaboration documents

Inconsistent alignment

[ih-codes]

Suggested change

	When an investigation or proposal results in a technical decision, the responsible engineer will author an **ADR in GitHub** to record that decision.
	After a decision is made, any resulting documentation that becomes part of long-term knowledge (e.g., implementation guides, architecture updates) will be written in **Confluence**, with optional links back to the relevant Drive documents for historical context.
	Google Drive will therefore remain the home for **exploration and discovery**, while **GitHub ADRs** and **Confluence** represent **decision** and **documentation**, respectively.
	When an investigation or proposal results in a technical decision, the responsible engineer will author an **ADR in GitHub** to record that decision. After a decision is made, any resulting documentation that becomes part of long-term knowledge (e.g., implementation guides, architecture updates) will be written in **Confluence**, with optional links back to the relevant Drive documents for historical context.
	Google Drive will therefore remain the home for **exploration and discovery**, while **GitHub ADRs** and **Confluence** represent **decision** and **documentation**, respectively.

Just a suggestion to combine the first 2 paragraphs. But at the very least there's an extra newline in here.

[ih-codes]

Suggested change

	Internal Confluence pages may be referenced in name only (e.g., “For Mozilla staff, see the internal Confluence page on Swift Concurrency for more details”) but should never be linked directly.
	Internal Confluence pages may be referenced in name only (e.g., “For Mozilla staff, see the internal Confluence page on Swift Concurrency for more details”) but should never be linked directly to ensure a good user experience for our contributors who can't access those documents.

Just a suggestion to clarify the "why"

[lmarceau]

What does evergreen means in this context?

[Cramsden]

This is confusing. I will change it. evergreen is basically another word for a living document

[Cramsden]

@lmarceau I have updated this sentence to be more clear. Let me know what you think!

[OrlaM]

Evergreen is a synonym for something living, so in terms of documentation it usually refers to a document that will continue to be used, referenced and updated as needed. E.g. documents outlining process of all kinds tend to be living/evergreen documents, because they often continue to evolve over time.