From db6c0dc7407d9156f3f8bb0f83a0b999bbc0440f Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Mon, 3 Aug 2026 16:02:29 -0700 Subject: [PATCH 1/7] Introduce documentation standardization for at all communication levels --- ...dopt-engineering-documentation-standard.md | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/architecture/adr/0034-adopt-engineering-documentation-standard.md diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md new file mode 100644 index 000000000..7e15a7f33 --- /dev/null +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -0,0 +1,105 @@ +--- +adr: "0034" +status: Proposed +date: 2026-07-22 +tags: [clients, mobile, server, sdk] +--- + +# 0034 - Adopt engineering documentation standard + + + +## Context and problem statement + +Documentation practice has fragmented as the organization has grown: + +- Major repos use divergent layouts (`docs/`, `Docs/`, per-crate READMEs, none), inconsistent README + casing and quality, and no shared definition of what must be documented where. +- The de facto standards page lives in Confluence and is not enforced; practice diverges from it. +- Content sits in the wrong home: single-repo architecture on this site, shipped-code architecture + deep dives in Confluence, production runbooks in personal spaces, and duplicated guidance across + homes. +- Stale content accumulates with no supersession discipline, leaving superseded pages beside current + ones with no deprecation. +- AI agents have become first-class documentation consumers and maintainers (CLAUDE.md, rules, and + skills across all repos), with no governing standard tying instruction files to the docs they + reference. + +A 2026-07 audit classified every documentation artifact across the major repos, this site, and +Confluence against a proposed routing model, confirming these gaps. + +## Considered options + +- **Status quo:** per-team conventions, advisory Confluence page. +- **Confluence-first:** centralize engineering docs in the wiki. +- **Per-repo standards:** each repo defines its own documentation rules and keeps its own ADRs. +- **One org-wide, docs-as-code documentation standard:** close-to-code default, single routing + model, enforced through PR review and AI-agent guardrails. + +## Decision outcome + +Chosen option: **one org-wide, docs-as-code documentation standard**, published as the Documentation +section under Contributing on this site. The standard is the living reference. Its rules evolve by +PR without superseding this decision and this ADR is superseded only if the model itself changes. A +snapshot of the rules at adoption: + +1. **Public by default**. Private content is limited to documentation about working at Bitwarden and + sensitive information. +2. **Located at the lowest common ancestor** of what is described. +3. **Every doc has an audience**. AI agents and humans are both first-class audiences and + maintainers. + 1. AI instruction files point, documentation contains. +4. **Always up to date**. Doc maintenance is a top priority and happens alongside changes to what it + describes. +5. **Discoverable and unified**, enforced by the style guide the standard publishes. + +Diagrams follow the separate diagram standard adopted in +[ADR-0033](./0033-adopt-mermaid-diagram-standard.md), which keeps its own living reference at +Contributing › Diagrams. + +### Positive consequences + +- One place to answer "where does this doc live" and "which docs do I update", for engineers and AI + agents alike. +- Documentation rides the code PR, so freshness is enforced by review and agent guardrails. +- Public-by-default locations serve external contributors and AI agents without special access. + +### Negative consequences + +- A migration backlog: existing content sits in homes the routing model forbids and must move. +- Strict-move deletions can break unknown inbound links. Known links are updated at move time and + link checkers in CI are the mitigation for the rest. +- Every repo carries adoption work before the standard applies in practice. + +### Plan + +Follow-up PRs complete the standard: + +- The standard, with its format guidance and templates, publishes as the Documentation section under + Contributing and becomes the living reference this ADR mandates. +- The doc-currency plugin, which enforces rule 4, publishes in + [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) and distributes the root CLAUDE.md + documentation obligations. +- Each repo adopts the standard: base documentation obligations in the root CLAUDE.md, a + CONTRIBUTING pointer, and markdown tooling parity. +- Remediation work items are filed for every rule that current reality violates, and the superseded + Confluence standards page is deleted. + +The migration backlog proceeds opportunistically under named owners. Small one-shot fixes are +tracked as work items; the long-running efforts: + +- **Single-repo content migrates off this site**: `architecture/{clients,server,sdk,mobile-clients}` + and 12 of 28 deep-dive pages (including the whole `autofill/` subtree) move into their repos per + the routing table. Contributing docs' Deep Dives section holds only cross-repo or conceptual + material. +- **Shipped-code architecture migrates out of Confluence**: pages describing shipped code (the SSH + agent suite, event collection, key management cryptography) move in-repo or to this site per the + decision rule. +- **README coverage in `bitwarden/clients`**: generated stubs and missing module READMEs + (`libs/common`, `libs/components`, `libs/angular`) brought to the module README standard, and + filename casing normalized. +- **Confluence hygiene**: stale and superseded pages deleted or stale-marked, and team runbook + indexes adopt the runbook standard and its Last verified discipline. +- **Incident documentation consolidation**: RCAs converge on the incident.io export as the single + home. +- **Style long tail**: style violations fixed across the site as pages are touched. From f86488b3438dbf328e881c0c96569474d3067354 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Tue, 4 Aug 2026 15:35:33 -0700 Subject: [PATCH 2/7] Remove AI instruction files from documentation scope --- .../0034-adopt-engineering-documentation-standard.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index 7e15a7f33..ecd29ff83 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -21,9 +21,9 @@ Documentation practice has fragmented as the organization has grown: homes. - Stale content accumulates with no supersession discipline, leaving superseded pages beside current ones with no deprecation. -- AI agents have become first-class documentation consumers and maintainers (CLAUDE.md, rules, and - skills across all repos), with no governing standard tying instruction files to the docs they - reference. +- AI agents have become first-class documentation consumers and maintainers, and their instruction + files (CLAUDE.md, rules, and skills across all repos) accumulate documentation-like content with + nothing defining whether they are documentation at all. A 2026-07 audit classified every documentation artifact across the major repos, this site, and Confluence against a proposed routing model, confirming these gaps. @@ -48,7 +48,6 @@ snapshot of the rules at adoption: 2. **Located at the lowest common ancestor** of what is described. 3. **Every doc has an audience**. AI agents and humans are both first-class audiences and maintainers. - 1. AI instruction files point, documentation contains. 4. **Always up to date**. Doc maintenance is a top priority and happens alongside changes to what it describes. 5. **Discoverable and unified**, enforced by the style guide the standard publishes. @@ -57,6 +56,9 @@ Diagrams follow the separate diagram standard adopted in [ADR-0033](./0033-adopt-mermaid-diagram-standard.md), which keeps its own living reference at Contributing › Diagrams. +AI instruction files are explicitly not documentation and are out of the standard's scope. Their +guidance lives with the AI tooling. + ### Positive consequences - One place to answer "where does this doc live" and "which docs do I update", for engineers and AI From 2f0b8a433aac8c8c729701e0ea1227c57f07678d Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 10:30:38 -0700 Subject: [PATCH 3/7] Bump ADR date to PR request date --- .../adr/0034-adopt-engineering-documentation-standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index ecd29ff83..3322d0b1c 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -1,7 +1,7 @@ --- adr: "0034" status: Proposed -date: 2026-07-22 +date: 2026-08-05 tags: [clients, mobile, server, sdk] --- From 17c4a816c1de58e9f741b095be5cc8b6c9377f0a Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 10:33:24 -0700 Subject: [PATCH 4/7] wrap filename references in `` --- .../0034-adopt-engineering-documentation-standard.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index 3322d0b1c..b6a71be08 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -22,7 +22,7 @@ Documentation practice has fragmented as the organization has grown: - Stale content accumulates with no supersession discipline, leaving superseded pages beside current ones with no deprecation. - AI agents have become first-class documentation consumers and maintainers, and their instruction - files (CLAUDE.md, rules, and skills across all repos) accumulate documentation-like content with + files (`CLAUDE.md`, rules, and skills across all repos) accumulate documentation-like content with nothing defining whether they are documentation at all. A 2026-07 audit classified every documentation artifact across the major repos, this site, and @@ -80,10 +80,10 @@ Follow-up PRs complete the standard: - The standard, with its format guidance and templates, publishes as the Documentation section under Contributing and becomes the living reference this ADR mandates. - The doc-currency plugin, which enforces rule 4, publishes in - [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) and distributes the root CLAUDE.md - documentation obligations. -- Each repo adopts the standard: base documentation obligations in the root CLAUDE.md, a - CONTRIBUTING pointer, and markdown tooling parity. + [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) and distributes the root + `CLAUDE.md` documentation obligations. +- Each repo adopts the standard: base documentation obligations in the root `CLAUDE.md`, a + `CONTRIBUTING` pointer, and markdown tooling parity. - Remediation work items are filed for every rule that current reality violates, and the superseded Confluence standards page is deleted. From 1134bca699d34a8dbe9952cc14f4d539312b0165 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 10:45:40 -0700 Subject: [PATCH 5/7] Open up ADR plan to drift outside of clients repository Audit showed that clients was the one that needed attention, but drift may occur between proposal and acceptance. We need to bring all repos up to compliance --- .../adr/0034-adopt-engineering-documentation-standard.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index b6a71be08..d8ca89fc4 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -97,9 +97,8 @@ tracked as work items; the long-running efforts: - **Shipped-code architecture migrates out of Confluence**: pages describing shipped code (the SSH agent suite, event collection, key management cryptography) move in-repo or to this site per the decision rule. -- **README coverage in `bitwarden/clients`**: generated stubs and missing module READMEs - (`libs/common`, `libs/components`, `libs/angular`) brought to the module README standard, and - filename casing normalized. +- **README coverage in Bitwarden repositories**: generated stubs and missing module READMEs brought + to the module README standard, and filename casing normalized. - **Confluence hygiene**: stale and superseded pages deleted or stale-marked, and team runbook indexes adopt the runbook standard and its Last verified discipline. - **Incident documentation consolidation**: RCAs converge on the incident.io export as the single From 017b2d1d6b77e816a5deb4f51963a19fec32bcb1 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Fri, 7 Aug 2026 08:04:48 -0700 Subject: [PATCH 6/7] Less specific plan requirements allows for flexibility of implementation without altering the plan --- .../adr/0034-adopt-engineering-documentation-standard.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index d8ca89fc4..b5359dc1b 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -79,9 +79,9 @@ Follow-up PRs complete the standard: - The standard, with its format guidance and templates, publishes as the Documentation section under Contributing and becomes the living reference this ADR mandates. -- The doc-currency plugin, which enforces rule 4, publishes in - [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) and distributes the root - `CLAUDE.md` documentation obligations. +- An ai-plugin is produced and made available to help identify when local documents needs to be + updated as well as adding both local and external documentation update requirements to AI review + tools. - Each repo adopts the standard: base documentation obligations in the root `CLAUDE.md`, a `CONTRIBUTING` pointer, and markdown tooling parity. - Remediation work items are filed for every rule that current reality violates, and the superseded From e8122b03ba4ef2e7cbf89f4898605a8d5b3df651 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Fri, 7 Aug 2026 08:16:57 -0700 Subject: [PATCH 7/7] Update docs/architecture/adr/0034-adopt-engineering-documentation-standard.md Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- .../adr/0034-adopt-engineering-documentation-standard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index b5359dc1b..3382a22c1 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -79,7 +79,7 @@ Follow-up PRs complete the standard: - The standard, with its format guidance and templates, publishes as the Documentation section under Contributing and becomes the living reference this ADR mandates. -- An ai-plugin is produced and made available to help identify when local documents needs to be +- An ai-plugin is produced and made available to help identify when local documents need to be updated as well as adding both local and external documentation update requirements to AI review tools. - Each repo adopts the standard: base documentation obligations in the root `CLAUDE.md`, a