From db6c0dc7407d9156f3f8bb0f83a0b999bbc0440f Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Mon, 3 Aug 2026 16:02:29 -0700 Subject: [PATCH 01/10] 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 02/10] 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 03/10] 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 04/10] 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 05/10] 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 27e3a22c437730f437247d8d13d1cd19b651d219 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Tue, 4 Aug 2026 15:40:23 -0700 Subject: [PATCH 06/10] fill in documentation standard for adr 0034 --- .claude/CLAUDE.md | 4 +- custom-words.txt | 3 + .../0033-adopt-mermaid-diagram-standard.md | 18 +- ...dopt-engineering-documentation-standard.md | 12 +- docs/architecture/adr/index.mdx | 62 ++++ .../documentation/component-documentation.md | 62 ++++ .../{ => documentation}/diagrams.md | 2 +- docs/contributing/documentation/index.md | 278 ++++++++++++++++++ .../documentation/runbook-template.md | 83 ++++++ 9 files changed, 507 insertions(+), 17 deletions(-) create mode 100644 docs/contributing/documentation/component-documentation.md rename docs/contributing/{ => documentation}/diagrams.md (99%) create mode 100644 docs/contributing/documentation/index.md create mode 100644 docs/contributing/documentation/runbook-template.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index afb6d1ace..c48d71a32 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -108,7 +108,9 @@ for full ownership details. ### Architecture documentation - ADRs go in `docs/architecture/adr/` with format `####-title.md` -- Follow existing ADR structure (Status, Context, Decision, Consequences) +- Follow the MADR structure from the template on the ADR index (`docs/architecture/adr/index.mdx`): + frontmatter (`adr`, `status`, `date`, `tags`), Context and problem statement, Considered options, + Decision outcome ## Testing before committing diff --git a/custom-words.txt b/custom-words.txt index b0efcb94b..6329a5217 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -22,6 +22,7 @@ deprioritized diffable dockerized dotfile +evals F-Droid frontmatter Gitter @@ -52,6 +53,7 @@ LLDB Lucidchart Mailcatcher minio +mortems MVVM NGRX Napi @@ -107,6 +109,7 @@ typecheck typechecks typesafe udeps +ungated unsynchronized WCAG weweave diff --git a/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md b/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md index 57be3db80..5749003a2 100644 --- a/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md +++ b/docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md @@ -37,9 +37,9 @@ audience-specific views -- requires substantial rework per audience in practice. ## Decision outcome Chosen option: **Mermaid with defined conventions**, published as the -[diagram standard](../../contributing/diagrams.md) on the contributing site. The standard is the -living reference and its rules evolve by PR without superseding this decision. This ADR is -superseded only if the chosen option itself changes. A snapshot of the rules at adoption: +[diagram standard](../../contributing/documentation/diagrams.md) on the contributing site. The +standard is the living reference and its rules evolve by PR without superseding this decision. This +ADR is superseded only if the chosen option itself changes. A snapshot of the rules at adoption: 1. Diagrams are Mermaid source text, nothing else: as Mermaid code blocks, or, if in Confluence, via Macro Pack's Mermaid diagram in text-input mode. @@ -80,12 +80,12 @@ superseded only if the chosen option itself changes. A snapshot of the rules at ### Plan -The standard is published at Contributing › Diagrams, and the bulk of the contributing site's -existing diagrams (PlantUML/Kroki sources, static diagram assets, and source-less images) have been -converted to comply, so the site becomes the reference implementation of the standard, with the -exceptions noted below. Elsewhere, legacy diagrams convert when their docs are next touched: images -and non-Mermaid sources in repos become Mermaid code blocks, and Confluence attachments and images -become Macro Pack's Mermaid diagram in text-input mode. +The standard is published at Contributing › Documentation › Diagrams, and the bulk of the +contributing site's existing diagrams (PlantUML/Kroki sources, static diagram assets, and +source-less images) have been converted to comply, so the site becomes the reference implementation +of the standard, with the exceptions noted below. Elsewhere, legacy diagrams convert when their docs +are next touched: images and non-Mermaid sources in repos become Mermaid code blocks, and Confluence +attachments and images become Macro Pack's Mermaid diagram in text-input mode. The remaining adoption work is delegated to its owners: diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index d8ca89fc4..edb66d209 100644 --- a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md +++ b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md @@ -1,6 +1,6 @@ --- adr: "0034" -status: Proposed +status: Accepted date: 2026-08-05 tags: [clients, mobile, server, sdk] --- @@ -38,10 +38,10 @@ Confluence against a proposed routing model, confirming these gaps. ## 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: +Chosen option: **one org-wide, docs-as-code documentation standard**, published as the +[Documentation section](../../contributing/documentation/index.md). 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. @@ -54,7 +54,7 @@ snapshot of the rules at adoption: 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. +Contributing › Documentation › Diagrams. AI instruction files are explicitly not documentation and are out of the standard's scope. Their guidance lives with the AI tooling. diff --git a/docs/architecture/adr/index.mdx b/docs/architecture/adr/index.mdx index 10f220e9a..d398292ff 100644 --- a/docs/architecture/adr/index.mdx +++ b/docs/architecture/adr/index.mdx @@ -75,6 +75,68 @@ the thinking process and alternatives considered rather than simply stating what if an ADR doesn't cover every edge case or alternative it provides valuable context and can be refined through discussion. +## Format + +ADRs follow the [MADR](https://adr.github.io/madr/) structure: a context and problem statement, the +considered options, and the decision outcome with its consequences. Start from the template below. + +Each ADR is a file named `NNNN-short-title.md` in `docs/architecture/adr/`, numbered with the next +unused number. Refer to an ADR elsewhere by that number as ADR-NNNN, linking the file relatively so +the reference survives a move of this section. + +
+ADR template + +Delete the guidance comments before opening the pull request. + +```text +--- +adr: "NNNN" +status: Proposed +date: YYYY-MM-DD +tags: [clients, mobile, server, sdk] +--- + +# NNNN - Short imperative title + + + +{/* Optional "## Notation" section here if the ADR relies on notation (RFC 2119 + keywords, symbols). Delete when unused. */} + +## Context and problem statement + +{/* 2–4 paragraphs. What situation forces a decision? What breaks or + stays painful if we decide nothing? Link code, issues, and prior ADRs. */} + +## Considered options + +- **Option A:** one-line description. +- **Option B:** one-line description. + +{/* Optional per-option subsections with pros/cons when the tradeoffs + need more than a line. Include "do nothing" when it is a real option. */} + +## Decision outcome + +Chosen option: **Option A**, because {decisive reason}. + +### Positive consequences + +- ... + +### Negative consequences + +- ... + +### Plan + +{/* How the decision takes effect: the follow-up work, migrations, and owners. + Delete when the ADR needs no follow-up. */} +``` + +
+ ## Status definition ADRs progress through different statuses throughout their lifecycle. Understanding these statuses diff --git a/docs/contributing/documentation/component-documentation.md b/docs/contributing/documentation/component-documentation.md new file mode 100644 index 000000000..1344b28bb --- /dev/null +++ b/docs/contributing/documentation/component-documentation.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 1 +--- + +# Component documentation + +**Audience:** Bitwarden engineers and AI agents writing or consuming in-repo documentation. + +Notation follows the [documentation standard's Notation](./index.md#notation). These requirements +hold for every repo for as long as it lives, enforced by review and the doc-currency plugin. New +repositories satisfy them at initialization by starting from +[bitwarden/template](https://github.com/bitwarden/template). Existing repos converge per +[Changes to this standard](./index.md#changes-to-this-standard). Additional local guidance MAY be +layered on top, as each situation dictates. + +Any component that other engineers or agents consume (that is, it exposes a public interface) MUST +have an **entry point for its scope's documentation**, at every scope from a single component to the +repo root. The entry point lives where the component's ecosystem surfaces documentation: + +- At **component scope**, the entry point is the `README.md`, which registries render for packaged + components (a crate, an npm package, a NuGet project). Rust crates keep the README and the rustdoc + landing page one artifact with `#![doc = include_str!("../README.md")]`. +- **Below component scope**, the entry point is the language's module-level documentation where it + exists (`//!` in Rust), since a README there duplicates what the toolchain already owns and no + tooling surfaces it. It SHOULD be lint-enforced where the language supports it (Rust's + `missing_docs`). +- At **container and system scopes** (a container grouping several components, the repo root), the + entry point is a `README.md`, since no language ecosystem claims them. + +Whatever its carrier, the entry point MUST contain: + +1. **Purpose:** what problem this component solves, in 1–3 sentences. +2. **Key concepts:** the domain model or invariants a consumer must know (e.g., `libs/state`'s + data-loss warning on key renames; `bitwarden-crypto`'s `derive_`/`make_` naming rules). +3. **Usage:** the primary entry points, with a short code sample where the API is not self-evident. +4. **Gotchas / constraints:** the things that bite people (e.g., `libs/auth`'s "do not add new code + here" notice). This section MUST exist when such constraints do and MUST NOT exist when they do + not. + +Documentation grows outward from the entry point of the +[lowest common ancestor](./index.md#where-documentation-lives-rules-1-2) of the code it describes. A +guide spanning several components therefore belongs to their parent scope: + +1. Everything starts at the scope's entry point. +2. A single topic that deserves its own document becomes a named `.md` next to the code it + describes, linked from the entry point (`apps/browser/src/autofill/lifecycle.design.md` is the + exemplar). +3. When the scope's documentation outgrows this, it splits into a `docs/` folder (exactly that name, + lowercase) at the scope root. `docs/` exists only beside the entry point it extends: at the repo + root (`clients/docs/cipher-types.md` is the exemplar) or a component with its own entry point + (`util/Seeder/Seeds/docs/`), never an arbitrary subdirectory. + +Scopes layer and multiple perspectives exist. A parent scope's documentation MAY describe the same +code at a higher altitude, sanding off detail the deeper docs own and linking down to them, and the +same subject MAY be documented separately per audience. Both are approved. Duplication is two +artifacts sharing one perspective. + +Below component scope, reference documentation is code: doc comments on public symbols, reviewed and +merged with functionality, lint-enforced where the platform supports it. Doc comments MUST follow +the language's documentation norms for structure and detail. Where not enforced by the type system, +doc comments MUST say what a caller needs (behavior, invariants, error cases). Repos with doc CI +SHOULD fail the build on broken docs (the `sdk-internal` `cargo doc -D warnings` pattern). diff --git a/docs/contributing/diagrams.md b/docs/contributing/documentation/diagrams.md similarity index 99% rename from docs/contributing/diagrams.md rename to docs/contributing/documentation/diagrams.md index 84618fe1b..6edccca60 100644 --- a/docs/contributing/diagrams.md +++ b/docs/contributing/documentation/diagrams.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 5 --- # Diagram standard diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md new file mode 100644 index 000000000..565451d3c --- /dev/null +++ b/docs/contributing/documentation/index.md @@ -0,0 +1,278 @@ +--- +sidebar_position: 2 +sidebar_label: Documentation +--- + +# Documentation standard + +**Audience:** Bitwarden engineers who write and maintain technical documentation, and AI agents that +read documentation to work in our codebases. External contributors are a secondary audience. + +## Notation + +The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in +[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +`repo` is short for repository, referring to a git repository. + +`doc` or `docs` is short for documentation. + +`PR` is short for pull request. + +`RCA` is short for root cause analysis, the post-incident review document. + +`CI` is short for continuous integration. + +`system`, `container`, and `component` describe software scope as the +[diagram standard](./diagrams.md) defines them: C4 vocabulary, where a component is a major part +inside one container (a library, a crate, a feature root). + +`›` marks a location in a site or page hierarchy ("contributing.bitwarden.com › Architecture"). + +`→` marks a routing outcome ("cross-repo architecture → contributing.bitwarden.com"). Read as +"then". + +## The standard + +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. +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 published here. + +## Where documentation lives (rules 1, 2) + +The **lowest common ancestor** of a doc's subject is the deepest scope that contains everything it +describes: a component for component docs, a repo root for repo-spanning guides, +contributing.bitwarden.com for subjects above any one repo, and a private location when +[rule 1](#private-content) removes the public homes from consideration. Every doc lives there and +nowhere else. Close to code is the common case: in-repo docs ride the same PR and review as the +change and are visible to AI agents working in the tree. + +Within a scope, documentation is one growing artifact: it starts at the scope's entry point, +typically its `README.md`, and splits into a `docs/` folder beside it when it outgrows one file, per +[Component documentation](./component-documentation.md). Wherever this standard says `README.md` or +`docs/`, it means that artifact at either stage. + +AI instruction files (CLAUDE.md, rules, skills) are not documentation: they are instructions on how +to behave and how to consume documentation. This standard does not govern them, and content that +belongs in documentation MUST NOT live in an instruction file, since that would give it a second +home. + +One home holds one **perspective**: the audience a doc serves and the question it answers. A +different audience or altitude is a different [perspective](./diagrams.md), not a duplicate. Link +related perspectives to each other, and link instead of copying, since duplicated guidance always +diverges. + +### Decision rule + +Apply in order. First match wins: + +1. Is it [Private content](#private-content)? → a **private location:** + [bitwarden/tech-breakdowns](https://github.com/bitwarden/tech-breakdowns)bitwarden/tech-breakdowns + for tech breakdowns and work specifications, **Confluence** in the owning team's space for + everything else. +2. Does it describe **code in one repo**? → **that repo**, in the owning scope's + [README.md or docs/](./component-documentation.md). +3. Is it **how to contribute or build**, **architecture spanning repos**, or an **architectural + decision**? → **contributing.bitwarden.com** + ([bitwarden/contributing-docs](https://github.com/bitwarden/contributing-docs)), behind the + `` audience gate when the concern is internal-only. + +:::note + +1. This rule fires first because `` gating is not secrecy: it is convenience and + effective communication. +2. Repo-specific practice guides (testing, troubleshooting, tooling tips coupled to the repo's + scripts or lint config) follow this rule. +3. Environment setup and onboarding follow this rule even when repo-specific. Internal content does + not move to Confluence merely for being internal. It MUST be sensitive or organizational. + +::: + +### Private content + +Exactly two categories of content are private: + +- **Content Bitwarden cannot expose**: sensitive infrastructure, security-operational detail. + Feature and work planning also belong here, since direction is private until work begins. +- **Content about working at Bitwarden** rather than working on its code: people processes, on-call, + incident response, and team/org process. + +Everything else defaults to public. Bitwarden builds in the open and public docs serve external +contributors without special access. The litmus test is + +> Anything about **how to write or build Bitwarden code** goes somewhere public. + +Confluence holds what we cannot expose and the business of working at Bitwarden, not engineering +knowledge. + +### Reverse routing table + +Where each kind of documentation lives, grouped by home. Owners follow the +[ownership rule](#owners). The Format column links the page that owns the type's format, where one +exists. When more than one row fits, the most specific row wins. This applies within a group or +between multiple. + +Per rule 4, every type updates alongside what it describes. Four types carry their own cadence +besides: runbooks re-verify on every execution, changelogs update every release, RCAs follow the +incident process, and team process pages are at the owning team's discretion. + +A type not listed here is routed with the [decision rule](#decision-rule) and then added, by PR, to +the group matching its home. If the rule does not route it cleanly, that is a bug in this standard: +propose the fix and the new row in the same PR. + +#### In the repo + +| Documentation type | Home | Format | +| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------- | +| Component docs: what one library, crate, or feature does and how to use it | `README.md` (or the component's `docs/`) next to the code | [Component documentation][component-docs] | +| Guides spanning multiple components in one repo | `docs/` or README at the components' lowest common ancestor | [Component documentation][component-docs] | +| Architecture of one repo | The owning scope's `docs/` or README | [Component documentation][component-docs] | +| Repo overview, build entry point | Root `README.md` | The [bitwarden/template][template] README skeleton | +| New-repo doc scaffolding (README skeleton, CONTRIBUTING pointer, `.claude/`) | [bitwarden/template][template] | — | +| Repo-specific code style overrides (coupled to lint/formatter config) | Repo `docs/`, linking the org baseline | — | +| API / SDK reference | Doc comments in source | [Component documentation][component-docs] | +| UI component library usage docs (audience: developers **and** designers) | `.mdx` colocated with the UI component, rendered at [components.bitwarden.com][storybook] | Storybook `autodocs` | +| Changelog for a published artifact | `CHANGELOG.md` next to the artifact | Ecosystem convention | +| Platform-mandated files (`SECURITY.md`, `.github` templates, CODEOWNERS, registry READMEs, store metadata) | Path fixed by the platform | Platform-defined | +| Legal, licensing, and trademark notices | Repo root | — | + +#### On contributing.bitwarden.com + +| Documentation type | Home | Format | +| -------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------- | +| Contribution how-to, environment setup, org-wide code style | contributing.bitwarden.com › Contributing | — | +| Org-wide engineering standards (this standard, AI review guidelines) | contributing.bitwarden.com › Contributing | — | +| Architecture decision records | [contributing.bitwarden.com › Architecture › ADRs][adr-index] | Template on the [ADR index][adr-index] | +| Architecture spanning repos | contributing.bitwarden.com › Architecture | — | +| Deep dives (cross-repo or conceptual) | contributing.bitwarden.com › Architecture › Deep Dives | — | +| Security principles & requirements | [contributing.bitwarden.com › Architecture › Security][security] | — | + +#### In private locations + +| Documentation type | Home | Format | +| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Runbooks, on-call, operational docs | Confluence, owning **team** space | [Runbook template][runbook-template]Runbook template (internal) | +| Incident post-mortems / RCAs | incident.io → Confluence export (IP space only) | incident.io process | +| Infrastructure and deployment architecture | Confluence, owning team space | — | +| Production change records | Confluence, owning team space | — | +| Team & org process: planning, assessments, investigations, onboarding and hiring, directories, working groups | Confluence team space | — | +| Tech breakdowns / work specifications | [bitwarden/tech-breakdowns][tech-breakdowns]bitwarden/tech-breakdowns (private repo) | — | + +[component-docs]: ./component-documentation.md +[runbook-template]: ./runbook-template.md +[template]: https://github.com/bitwarden/template +[storybook]: https://components.bitwarden.com +[adr-index]: ../../architecture/adr/index.mdx +[security]: ../../architecture/security/index.mdx +[tech-breakdowns]: https://github.com/bitwarden/tech-breakdowns + +## Audience (rule 3) + +Documents without a targeted audience lack focus. Even if the original author had a specific +audience in mind, the living and collaborative nature of our documentation makes an explicit +audience callout necessary. Every isolated (not directly attached to code) document MUST include an +audience the document is written for. + +## Documentation updates (rule 4) + +The only thing that is worse than missing documentation is inaccurate documentation. It misinforms, +wastes time, and frustrates. This standard is designed to maximize the amount of documentation that +can be kept in lock-step with the code it describes, and the **doc-currency plugin**, which every +repo MUST adopt from [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins), enforces it: +at agent execution time for in-repo docs, and at review time for external docs. When a change +invalidates an external doc, a work item MUST be created before merge and the doc MUST receive a +[stale marker](#stale-markers) at the same time. The work item is done when the marker comes off, +and prioritization belongs to the owning team. Finally, the PR checklist item "Updated any necessary +documentation" reminds the PR author to update docs, and the reviewer validates it like code. + +### Deleting is maintenance + +When code is removed, remove its docs. Moving or replacing a doc is a **strict move**: the old +location MUST be deleted and known inbound links MUST be updated. ADRs are the exception: they are +historical records, so their supersession is a status change with a link to the successor, never a +deletion. + +Similarly, when decisions or trends change, docs MUST be updated to reflect the new reality. +Documents MUST NOT maintain a historic record of prior thinking, breadcrumb artifacts of the path to +the current state, or tedious enumerations of prior misunderstandings. + +### Stale markers + +Documentation known to be outdated but not yet fixable gets a top-of-file banner: +`⚠️ Outdated (YYYY-MM-DD): , per . Fix tracked by .` +Stale documentation is worse than none because it confidently misleads. Make inaccuracies known, +even when correction is not prioritized. + +### Owners + +Ownership follows CODEOWNERS for in-repo docs. Confluence pages name an owning team in the header +and SHOULD follow the owners of the Confluence space. + +Owners are responsible for the maintenance and general health of the documentation they own. + +### Changes to this standard + +A change to this standard that current reality violates ships with a remediation path in the same +change. This means tracked work items where the violations are enumerable, or a transition plan +(owned migrations, convert-on-touch policies, tracked deviations) where they are not. Existing +violations are named, never silently grandfathered. + +## Style guide (rule 5) + +Match form to content: walkthroughs and deep dives are prose, while reference material leans on +tables, lists, and rules. Both are legitimate. Code comments follow language norms +([Component documentation](./component-documentation.md)). + +- **Docs have a default entry point**: the index for Confluence and contributing.bitwarden.com, the + README for code repos. +- **Diagrams follow the [diagram standard](./diagrams.md)**. +- **Concise, single-purpose.** Sprawling documentation is hard to maintain and a chore to consume. + Write the minimum that serves the audience, and delete what does not. +- **Highly linked.** Link to supporting and related docs, since linking is what enables concise, + single-purpose documents. + - Say what is behind the link ("the ADR index explains statuses", not "see here"). + - Relative links within a repo, full URLs across repos and sites. + - Public pages MUST NOT link to internal-only destinations outside a `` gate, since + external contributors cannot access them. +- **Lead with the point.** Open with what the reader came for: what the component does, how the flow + works, the takeaway. Background, rationale, and edge cases follow. +- **Sentence case** for all headings ("Considered options", not "Considered Options"). +- **Headings mark lookup targets.** Add one where a reader would search or deep-link, never to break + up text. +- **Procedures** are numbered steps starting with a verb ("Run…", "Open…", "Set…"). One command per + fenced code block, never inline, always with a language tag. State expected output when it is not + obvious. +- **Code samples are real**: taken from or verified against the actual codebase, with file paths + (`libs/state/README.md` style). +- **No invented shorthand.** Spell out space, section, and product names. A reader should not need + to decode abbreviations the document never defines. +- **Formatting is tooling's job**: Prettier and cspell where the repo has them. Repos SHOULD adopt + both plus a link checker in CI. + +### Standards documents + +Normative documents like this one (org-wide standards, the diagram standard) carry additional +formality, since readers and tooling act on their exact wording: + +- **RFC 2119 keywords** in all caps mark requirement levels. Define them, and any other notation the + document relies on, in a [Notation](#notation) section up front. +- **Lead with the rules**: a numbered rule list up top, elaboration sections tagged by the rules + they explain. +- **Rationale rides in a trailing `:::note`** whose numbering matches the rules, as the + [decision rule](#decision-rule) does, or attaches with "since" or "because". No em-dash, + parenthetical, or semicolon asides, and no asides that only dramatize a rule. +- **No contractions.** Write "do not", "cannot", and "it is" in full. + +## Definition of done + +A documentation change (or the doc portion of a code change) is done when it satisfies +[the standard](#the-standard) and the [style guide](#style-guide-rule-5). + +For a **code** change, every README, `docs/` page, diagram, doc comment, and CLAUDE.md that +describes the changed behavior MUST be updated in the same PR. If none described it but it warrants +documentation per the [component README standard](./component-documentation.md), add it. diff --git a/docs/contributing/documentation/runbook-template.md b/docs/contributing/documentation/runbook-template.md new file mode 100644 index 000000000..f355108b2 --- /dev/null +++ b/docs/contributing/documentation/runbook-template.md @@ -0,0 +1,83 @@ +--- +sidebar_position: 3 +sidebar_custom_props: + access: bitwarden +--- + +# Runbook template + + + +**Audience:** Bitwarden engineers authoring or executing runbooks. + +Notation follows the [documentation standard's Notation](./index.md#notation). + +This template produces Confluence pages in the owning team's space, under that space's runbook +index, never in a personal space. The structure below maps 1:1 to Confluence headings, and the +metadata block is a table at the top of the page. + +````markdown +# Runbook: (e.g., "Rotate data protection certificate") + +| | | +| -------------------- | ------------------------------------------------------- | +| **Owner** | (Slack: #) | +| **Audience** | | +| **Service / system** | | +| **Last verified** | YYYY-MM-DD by | +| **Supersedes** | | +| **Risk** | | + +## Notation + + + +## When to use this + +One or two sentences: the alert, symptom, or scheduled task that triggers this runbook. If there is +a related incident type or Datadog monitor, link it. + +## Prerequisites + +- Access needed (roles, groups, VPN, break-glass); link the request path. +- Tools needed and where to get them. +- Preconditions to confirm before starting (and how to confirm them). + +## Steps + +1. Verb-first instruction. + + ``` + one command per code block + ``` + + Expected output: . + +2. **⚠️ point of no return** Next step. Call out irreversible steps before the step, not after as + done for this step. + +## Verification + +How to confirm the overall operation succeeded before closing the page. + +## Rollback + +How to undo, or the explicit statement "not reversible past step N; escalate instead." + +## Escalation + +Who to page/ask when a step fails, in order (person/rotation, Slack channel, incident.io severity to +raise). +```` + +Rules: + +- **Last verified** is updated by whoever executes the runbook, every time; fixing drift found + during execution is part of executing. If not verified in 12 months, add a + `⚠️ Unverified since ` banner. +- One command per code block; no prose-embedded commands, since responders copy-paste under + pressure. +- When this runbook replaces another, delete the old page after updating known inbound links. +- Diagrams, if any, follow the [diagram standard](./diagrams.md). + + From a98cbc3e39eb054d128dcb576cbf6a828d4def08 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 11:08:57 -0700 Subject: [PATCH 07/10] wrap filename references in `` --- docs/contributing/documentation/diagrams.md | 2 +- docs/contributing/documentation/index.md | 36 ++++++++++----------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/contributing/documentation/diagrams.md b/docs/contributing/documentation/diagrams.md index 6edccca60..d2ca6a243 100644 --- a/docs/contributing/documentation/diagrams.md +++ b/docs/contributing/documentation/diagrams.md @@ -105,7 +105,7 @@ C4 is adopted as a **mental model only**. We are explicitly **NOT** adopting any ## Ownership and currency (rules 7 and 8) -- The owner is CODEOWNERS for in-repo docs and the page's owning team on Confluence. +- The owner is `CODEOWNERS` for in-repo docs and the page's owning team on Confluence. - Updates land in the same PR or page edit as the change the diagram depicts. A diagram known to be wrong is deleted or updated rather than left to mislead. - Every repo's root `CLAUDE.md` MUST carry the base documentation obligations, which cover diagrams: diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md index 565451d3c..04999fa7f 100644 --- a/docs/contributing/documentation/index.md +++ b/docs/contributing/documentation/index.md @@ -57,8 +57,8 @@ typically its `README.md`, and splits into a `docs/` folder beside it when it ou [Component documentation](./component-documentation.md). Wherever this standard says `README.md` or `docs/`, it means that artifact at either stage. -AI instruction files (CLAUDE.md, rules, skills) are not documentation: they are instructions on how -to behave and how to consume documentation. This standard does not govern them, and content that +AI instruction files (`CLAUDE.md`, rules, skills) are not documentation: they are instructions on +how to behave and how to consume documentation. This standard does not govern them, and content that belongs in documentation MUST NOT live in an instruction file, since that would give it a second home. @@ -76,7 +76,7 @@ Apply in order. First match wins: for tech breakdowns and work specifications, **Confluence** in the owning team's space for everything else. 2. Does it describe **code in one repo**? → **that repo**, in the owning scope's - [README.md or docs/](./component-documentation.md). + [`README.md` or `docs/`](./component-documentation.md). 3. Is it **how to contribute or build**, **architecture spanning repos**, or an **architectural decision**? → **contributing.bitwarden.com** ([bitwarden/contributing-docs](https://github.com/bitwarden/contributing-docs)), behind the @@ -127,19 +127,19 @@ propose the fix and the new row in the same PR. #### In the repo -| Documentation type | Home | Format | -| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------- | -| Component docs: what one library, crate, or feature does and how to use it | `README.md` (or the component's `docs/`) next to the code | [Component documentation][component-docs] | -| Guides spanning multiple components in one repo | `docs/` or README at the components' lowest common ancestor | [Component documentation][component-docs] | -| Architecture of one repo | The owning scope's `docs/` or README | [Component documentation][component-docs] | -| Repo overview, build entry point | Root `README.md` | The [bitwarden/template][template] README skeleton | -| New-repo doc scaffolding (README skeleton, CONTRIBUTING pointer, `.claude/`) | [bitwarden/template][template] | — | -| Repo-specific code style overrides (coupled to lint/formatter config) | Repo `docs/`, linking the org baseline | — | -| API / SDK reference | Doc comments in source | [Component documentation][component-docs] | -| UI component library usage docs (audience: developers **and** designers) | `.mdx` colocated with the UI component, rendered at [components.bitwarden.com][storybook] | Storybook `autodocs` | -| Changelog for a published artifact | `CHANGELOG.md` next to the artifact | Ecosystem convention | -| Platform-mandated files (`SECURITY.md`, `.github` templates, CODEOWNERS, registry READMEs, store metadata) | Path fixed by the platform | Platform-defined | -| Legal, licensing, and trademark notices | Repo root | — | +| Documentation type | Home | Format | +| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------- | +| Component docs: what one library, crate, or feature does and how to use it | `README.md` (or the component's `docs/`) next to the code | [Component documentation][component-docs] | +| Guides spanning multiple components in one repo | `docs/` or README at the components' lowest common ancestor | [Component documentation][component-docs] | +| Architecture of one repo | The owning scope's `docs/` or README | [Component documentation][component-docs] | +| Repo overview, build entry point | Root `README.md` | The [bitwarden/template][template] README skeleton | +| New-repo doc scaffolding (README skeleton, CONTRIBUTING pointer, `.claude/`) | [bitwarden/template][template] | — | +| Repo-specific code style overrides (coupled to lint/formatter config) | Repo `docs/`, linking the org baseline | — | +| API / SDK reference | Doc comments in source | [Component documentation][component-docs] | +| UI component library usage docs (audience: developers **and** designers) | `.mdx` colocated with the UI component, rendered at [components.bitwarden.com][storybook] | Storybook `autodocs` | +| Changelog for a published artifact | `CHANGELOG.md` next to the artifact | Ecosystem convention | +| Platform-mandated files (`SECURITY.md`, `.github` templates, `CODEOWNERS`, registry READMEs, store metadata) | Path fixed by the platform | Platform-defined | +| Legal, licensing, and trademark notices | Repo root | — | #### On contributing.bitwarden.com @@ -210,7 +210,7 @@ even when correction is not prioritized. ### Owners -Ownership follows CODEOWNERS for in-repo docs. Confluence pages name an owning team in the header +Ownership follows `CODEOWNERS` for in-repo docs. Confluence pages name an owning team in the header and SHOULD follow the owners of the Confluence space. Owners are responsible for the maintenance and general health of the documentation they own. @@ -273,6 +273,6 @@ formality, since readers and tooling act on their exact wording: A documentation change (or the doc portion of a code change) is done when it satisfies [the standard](#the-standard) and the [style guide](#style-guide-rule-5). -For a **code** change, every README, `docs/` page, diagram, doc comment, and CLAUDE.md that +For a **code** change, every README, `docs/` page, diagram, doc comment, and `CLAUDE.md` that describes the changed behavior MUST be updated in the same PR. If none described it but it warrants documentation per the [component README standard](./component-documentation.md), add it. From 86711f03cb3e5aa61d8278f7b3dbf6c147e13cdb Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 11:15:16 -0700 Subject: [PATCH 08/10] Exclude ADRs from audience requirements --- docs/contributing/documentation/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md index 04999fa7f..f83b5def4 100644 --- a/docs/contributing/documentation/index.md +++ b/docs/contributing/documentation/index.md @@ -175,8 +175,8 @@ propose the fix and the new row in the same PR. Documents without a targeted audience lack focus. Even if the original author had a specific audience in mind, the living and collaborative nature of our documentation makes an explicit -audience callout necessary. Every isolated (not directly attached to code) document MUST include an -audience the document is written for. +audience callout necessary. Apart from ADRs, every isolated (not directly attached to code) document +MUST include an audience the document is written for. ## Documentation updates (rule 4) From 6e66afd4f9a377004036d1ecab1cafa2094291a7 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Wed, 5 Aug 2026 11:15:28 -0700 Subject: [PATCH 09/10] Remove unused custom word --- custom-words.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/custom-words.txt b/custom-words.txt index 6329a5217..537626715 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -22,7 +22,6 @@ deprioritized diffable dockerized dotfile -evals F-Droid frontmatter Gitter From 3b6856cfe0fc0723a1460f94a99cab95312c75d5 Mon Sep 17 00:00:00 2001 From: Matt Gibson Date: Tue, 11 Aug 2026 07:58:04 -0700 Subject: [PATCH 10/10] Plugin renamed to avoid weird usage of currency --- .../adr/0034-adopt-engineering-documentation-standard.md | 2 +- docs/contributing/documentation/component-documentation.md | 2 +- docs/contributing/documentation/diagrams.md | 4 ++-- docs/contributing/documentation/index.md | 6 +++--- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md b/docs/architecture/adr/0034-adopt-engineering-documentation-standard.md index edb66d209..088dc4a70 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. -- The doc-currency plugin, which enforces rule 4, publishes in +- The doc-parity 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 diff --git a/docs/contributing/documentation/component-documentation.md b/docs/contributing/documentation/component-documentation.md index 1344b28bb..af85177d1 100644 --- a/docs/contributing/documentation/component-documentation.md +++ b/docs/contributing/documentation/component-documentation.md @@ -7,7 +7,7 @@ sidebar_position: 1 **Audience:** Bitwarden engineers and AI agents writing or consuming in-repo documentation. Notation follows the [documentation standard's Notation](./index.md#notation). These requirements -hold for every repo for as long as it lives, enforced by review and the doc-currency plugin. New +hold for every repo for as long as it lives, enforced by review and the doc-parity plugin. New repositories satisfy them at initialization by starting from [bitwarden/template](https://github.com/bitwarden/template). Existing repos converge per [Changes to this standard](./index.md#changes-to-this-standard). Additional local guidance MAY be diff --git a/docs/contributing/documentation/diagrams.md b/docs/contributing/documentation/diagrams.md index d2ca6a243..5dd640bc5 100644 --- a/docs/contributing/documentation/diagrams.md +++ b/docs/contributing/documentation/diagrams.md @@ -103,14 +103,14 @@ vocabulary. The example above is at context level. C4 is adopted as a **mental model only**. We are explicitly **NOT** adopting any C4 tooling/DSL. -## Ownership and currency (rules 7 and 8) +## Ownership and updates (rules 7 and 8) - The owner is `CODEOWNERS` for in-repo docs and the page's owning team on Confluence. - Updates land in the same PR or page edit as the change the diagram depicts. A diagram known to be wrong is deleted or updated rather than left to mislead. - Every repo's root `CLAUDE.md` MUST carry the base documentation obligations, which cover diagrams: when you change code that a diagram describes, update the diagram in the same change. The - doc-currency plugin in [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) distributes + doc-parity plugin in [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) distributes the obligation and enforces it across every documented scope above a change. The plugin's own documentation owns the mechanism. - Agent-authored diagrams follow the same rules. Generated diagrams MUST carry a perspective caption diff --git a/docs/contributing/documentation/index.md b/docs/contributing/documentation/index.md index f83b5def4..762451237 100644 --- a/docs/contributing/documentation/index.md +++ b/docs/contributing/documentation/index.md @@ -182,9 +182,9 @@ MUST include an audience the document is written for. The only thing that is worse than missing documentation is inaccurate documentation. It misinforms, wastes time, and frustrates. This standard is designed to maximize the amount of documentation that -can be kept in lock-step with the code it describes, and the **doc-currency plugin**, which every -repo MUST adopt from [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins), enforces it: -at agent execution time for in-repo docs, and at review time for external docs. When a change +can be kept in lock-step with the code it describes, and the **doc-parity plugin**, which every repo +MUST adopt from [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins), enforces it: at +agent execution time for in-repo docs, and at review time for external docs. When a change invalidates an external doc, a work item MUST be created before merge and the doc MUST receive a [stale marker](#stale-markers) at the same time. The work item is done when the marker comes off, and prioritization belongs to the owning team. Finally, the PR checklist item "Updated any necessary