ADR 0001: Adopt Docs as Code

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: Docs that live only in wikis or chat are easy to lose when people leave. They also drift from the code if nothing forces updates together. Docs as Code means we use the same tools as for the app (git, review, CI) for narrative content too: diagrams, API text, and guides move with commits and releases.

As the API grows, partners need one place to learn behavior, operators need runbooks that match production, and the team needs onboarding that does not rely on word of mouth. Updates without checks fall behind the real service.

Decision

We use Docs as Code as a standard practice:

1. Keep documentation in repository and version it with code.
2. Treat OpenAPI contracts, error schemas, and examples as part of public API contract.
3. Use command-driven generation/synchronization for docs artifacts.
4. Enforce documentation checks in quality gates before deployment.

Implementation in this repository

Section entry points: README.html

Each documentation section under docs/ uses a single HTML entry file named README.html (not index.html), so paths are consistent and predictable when browsing the tree in the editor or on Git hosting. Link to the section as …/section/README.html.

• docs/internal/developers.html — Developers Docs (engineering practices and index of guides under docs/developer/; docs/developer/README.html redirects here)
• docs/adr/README.html — ADR index
• docs/runbooks/README.html — runbooks index
• docs/backlog/README.html — product and quality backlog

Other human-readable docs

• Human docs:
  • README.md (repository root)
  • docs/internal/system-design.html
• Diagram sources:
  • docs/uml/**/*.puml
• Generated diagrams:
  • docs/uml/rendered/*.svg
• Sync tooling:
  • scripts/regenerate_docs.py
  • scripts/sync_docs.py
• Make targets:
  • make docs-fix
  • make docs-check (via make verify-ci locally; CI uses make verify + docs-fix)
  • make release-check
  • make release DEPLOY_CMD="..."

Authoring model

Narrative documentation under docs/adr/, docs/developer/, docs/runbooks/, and related trees is authored as HTML and normalized by scripts/format_docs_html.py. Optional Markdown files (*.md) in those folders are supported: when present, scripts/render_docs_html.py writes companion *.html next to them. Markdown is not required for those sections.

Quality gate: docs-check

make docs-check records git diff HEAD, runs docs-fix, and compares the diff again. If anything changed, committed generated output was stale—run make docs-fix and commit. See Documentation pipeline.

Consequences

Positive

• Documentation remains aligned with runtime behavior.
• Changes are auditable in PR history.
• Release process blocks stale docs and missing generated artifacts.

Trade-offs

• Slightly longer pre-release pipeline.
• Developers must run docs commands as part of regular workflow.

Usage

Typical workflow:

        make test
        make docs-fix
        make release-check
      

Page history