ADR 0001 — Engineering Knowledge Base (docs-as-code)

Status: Accepted · 2026-06-29

Context

Team documentation (starting with the Exercise AI PRDs) lived in Notion. We want to own our docs — no rented app, no API/fidelity tax — and make them readable by both humans and AI coding agents. The goal is a clean web UI to read and control documents, deliberately not a Notion/Confluence clone: no in-browser WYSIWYG editor and no real-time collaboration. That editor/collaboration layer is the expensive majority of a wiki product, and we skip it because we edit via git + IDE + AI + pull request.

Decisions

1. Content is markdown + frontmatter in git — the single source of truth. The rendered site is generated from it and never hand-edited. Edit the .md, the page updates (hot-reload in dev; rebuild on merge in production).
2. Repo: engineering-knowledge-base. “knowledge base” over “wiki” because the model is curated and PR-reviewed (not anyone-edits-in-browser), and because it is the term for the corpus an AI reads from. Structure: prds/ (first tenant), adr/, guides/, runbooks/, knowledge/. Make room for all; fill prds/ first; grow knowledge/ by accretion.
3. Render with Nextra. It is Next.js (our stack and deploy pipeline), allows a bespoke viewer UI, and ships built-in local search — no external search service, which suits self-hosting.
4. Editing is read-only render + an “Edit this page” link to Bitbucket. The reader edits/commits/opens a PR on Bitbucket; the deploy re-pulls. The app never writes files — all writes go through git.
5. Authorship comes from git. The commit author, timestamp, diff, and PR history are the audit log; “last updated by” is surfaced on the page from git.
6. AI reads the repo directly. Coding agents read the markdown from a checkout (grep/glob/open) — the same way they read code, with zero extra infrastructure. This replaces the previous Notion-connector read path.

Alternatives considered

• Docusaurus — strong (turnkey last-updated-author, versioning, larger ecosystem) but loses on stack-fit, bespoke-UI freedom, and adds an external search dependency; versioning isn’t needed.
• In-app WYSIWYG / git-backed CMS — deferred; it rebuilds the expensive half of a wiki product. Revisit only if editing-on-Bitbucket proves too heavy.
• Wiki naming — rejected: it connotes free-for-all browser editing, which is the opposite of this curated, reviewed model.

Consequences

• Low lock-in: markdown-in-git is portable; the framework is a replaceable view.
• Self-hosted; CI must do a full (non-shallow) clone for git-based “last updated” to work.
• Content is Vietnamese-first — fonts must have full Vietnamese diacritic coverage (a Vietnamese-complete sans is required; many serifs and display faces break on stacked diacritics).
• First content migrated: the five Exercise AI PRDs, under prds/exercise-ai/.