Skip to main content

ADR 0001 - Docs as Code

Status​

Accepted.

Context​

Playroll needs documentation that can grow with the codebase and support multiple audiences:

  • Developers need architecture and lifecycle contracts.
  • Testers need troubleshooting workflows.
  • Operators need release and monitoring runbooks.
  • Investors need stable KPI definitions and monitoring semantics.

Ad hoc ticket comments are not enough because they become hard to search and drift from the implementation.

Decision​

Maintain Playroll documentation as a static site in the playroll-docs repository.

Use curated Markdown/MDX pages for architecture, runbooks, and decision records. Use generated reference pages where source-of-truth extraction is practical, especially telemetry events and database schema documentation.

Consequences​

  • Documentation changes can be reviewed like code.
  • The site can be deployed as static files.
  • Broken links can be checked in CI.
  • Operational knowledge has a stable home outside Linear tickets and chat history.
  • The team must keep docs updated when changing lifecycle, telemetry, validation, database, or release behavior.