Alyson Docs

0001 — Docs as Code

Status: accepted

Context

We need a single place for Alyson AI documentation that covers product, services, data, operations, and decisions. Today it's scattered across Google Docs, Confluence, READMEs, Slack threads, and tribal knowledge. We want:

  • A central knowledge hub for engineers
  • A grep/retrieve-able context source for AI coding agents (Claude Code, Cursor, Codex, Copilot)
  • Version control of doc history alongside code conventions
  • Customizability for company branding, an eventual AI chat surface, and a docs dashboard
  • No paid tooling lock-in

Decision

Docs live in a dedicated Git repo (alyson-docs) as Markdown/MDX files. The repo is also a custom Next.js + Tailwind + Shadcn app that renders the Markdown into a documentation site, deployed on Vercel.

Source of truth: the Markdown files. The site is a view over them.

Alternatives Considered

Confluence / Notion / GitBook

  • Pros: WYSIWYG, no setup, non-eng friendly.
  • Cons: Paid (Confluence/GitBook), worse for AI retrieval (no clean Markdown), poor version control, painful to extend with custom UI (AI chat, dashboard).
  • Rejected: AI agents are a primary audience, and we want a custom-styled, brand-matched, extensible site.

Docusaurus (or MkDocs Material)

  • Pros: Batteries-included docs framework. Fast to set up.
  • Cons: Framework lock-in. Customizing layouts, adding non-doc pages (dashboard, future AI chat), or matching the company brand requires fighting the framework.
  • Rejected: We prefer a thin, owned stack over a heavy framework. We're a React shop; Next.js fits the existing skillset.

Per-repo docs/ folders only

  • Pros: Docs live next to code.
  • Cons: Hopping between repos kills flow for both humans and AI agents; no central site; cross-cutting product docs have no good home.
  • Rejected: See ADR-0002.

Consequences

Positive

  • Full control over rendering, navigation, branding, and what we add next (dashboard, AI chat).
  • Markdown source means AI agents can read it directly without scraping or APIs.
  • Version control, PR workflow, and code-style review apply to docs.
  • Vercel deploy is free for our scale.

Negative / trade-offs

  • We have to build navigation, search, syntax highlighting, etc. ourselves (libraries exist; not framework-level scaffolding).
  • More upfront engineering than Docusaurus.
  • Non-engineers need to use the GitHub web editor or be helped by an engineer to commit changes (mitigated by good templates and AI assistance).

Neutral / things we'll need to track

  • Site uptime and build performance (we control more, so we own more).
  • Doc staleness, addressed by ADR-0004 (TBD).

Implementation Notes

  • Stack: Next.js (App Router) + React + Tailwind + Shadcn + MDX (via next-mdx-remote).
  • Search: Pagefind, static, indexed at build.
  • Diagrams: Mermaid.
  • Dashboard: a regular Next.js page reading a generated JSON file.
  • Deploy: Vercel, GitHub-integrated.