Skip to content

ADR-0003: Migrate from Confluence to Docs as Code

Date: 2026-06-07
Status: Accepted
Decision makers: Dev team

Context

We had been using Confluence as our primary documentation platform. Over time it became a graveyard of outdated pages, hard to maintain, disconnected from the code it described, and with no clear ownership. Documentation written in Confluence had no relationship to the repos it covered, meaning it was rarely updated when code changed.

We needed documentation that lived closer to the code, was version-controlled, reviewable via PRs, and automatically kept in sync with the repos it described.

We considered:

  • Confluence (status quo) — hosted wiki, familiar, but disconnected from code and poorly maintained
  • Notion — better UX, but still disconnected from code and not version-controlled
  • Docs as code with MkDocs — Markdown files in Git, reviewed like code, auto-synced from source repos, deployed as a static site

Decision

We migrate all engineering documentation from Confluence to a docs-as-code approach using MkDocs with Material theme, hosted at dev-docs.subscribed.build via Cloudflare Pages.

Documentation lives in docs/ folders inside the repos they describe. The central eng-handbook repo aggregates documentation from all repos automatically via GitHub Actions, triggered whenever docs change in a source repo.

Confluence is no longer the source of truth for engineering documentation.

Consequences

Positive:

  • Documentation is version-controlled and reviewed via PRs like any other code change
  • Docs stay close to the code — ownership is clear
  • Auto-sync ensures the handbook reflects the current state of each repo
  • Search, navigation, and dark mode out of the box
  • Access-controlled via Cloudflare Zero Trust — only team members can reach it

Negative / trade-offs:

  • Markdown requires slightly more discipline than a wiki editor
  • Initial migration effort: existing Confluence content must be ported manually
  • Non-technical team members cannot contribute as easily

Mitigation:

  • Guides for adding new pages and contributing are part of the handbook itself
  • Confluence remains readable during transition but should not receive new engineering content