Skip to main content

ADR-021: Documentation SSOT Strategy

Status​

Accepted

Context​

The terraform-aws project generates documentation (ADRs, guides, module references) that must be published via the DevOps-TechDocs Docusaurus site. Three sync strategies were evaluated:

  1. Git symlinks — DevOps-TechDocs symlinks pointing to terraform-aws directories
  2. Git submodules — terraform-aws added as a submodule in DevOps-TechDocs
  3. CI cross-repo push — GitHub Action pushes docs from terraform-aws to DevOps-TechDocs via PAT

Decision​

Reject all three sync mechanisms. DevOps-TechDocs is the single source of truth (SSOT) for all published documentation.

  • Git stores symlinks as relative filesystem paths — they break on CI runners and other machines where repos are not co-located
  • Docusaurus does not follow symlinks outside the docs/ root
  • Breaks on Windows (junction vs symlink semantics)

Why submodules were rejected​

  • Reverses SSOT ownership (DevOps-TechDocs currently owns enriched content with Docusaurus frontmatter)
  • Requires submodules: recursive in every CI checkout job
  • Manual SHA bumps per content addition — the exact friction this aims to eliminate
  • Requires PAT secret management for private repos

Why CI cross-repo push was rejected​

  • Requires fine-grained PAT creation, rotation, and secret management
  • Push direction is wrong (terraform-aws pushing into DevOps-TechDocs contradicts SSOT ownership)
  • The stub workflow (docs-sync.yml) was never activated — H1-H3 HITL gates were never completed

Adopted pattern​

  • All documentation (ADRs, guides, invest stories) is authored and maintained directly in DevOps-TechDocs
  • sync-terraform-aws-docs.sh is a verification-only prebuild script (asserts >=19 ADRs exist)
  • docs-sync.yml in terraform-aws is renamed to "Generate Module README" — it only runs terraform-docs for module README auto-generation
  • No PATs, no submodule SHA bumps, no cross-environment symlink resolution

Consequences​

  • Positive: Zero cross-repo dependencies for documentation builds
  • Positive: No PAT secrets to manage or rotate
  • Positive: npm run build in DevOps-TechDocs is self-contained — all content is local
  • Positive: Docusaurus frontmatter (sidebar_position, tags) is maintained alongside content
  • Negative: New terraform-aws modules require manual guide addition in DevOps-TechDocs
  • Negative: ADR content exists only in DevOps-TechDocs, not co-located with module source code