Skip to main content

0034 - Adopt engineering documentation standard

ID:ADR-0034
Status:PROPOSED
Published:2026-08-05

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, 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.

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.
  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, 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 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.
  • 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 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 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 home.
  • Style long tail: style violations fixed across the site as pages are touched.