Docs Publishing Platform Strategy

Purpose

Define an IaC-first publishing model for readable, browsable, searchable documentation across Synkronyx core and product domains.

Decision

• GitHub remains the single source of truth for docs-as-code.
• Cloudflare Pages hosts published documentation sites.
• Azure DevOps wiki is maintained as a pointer-only landing page.

Domains

• Core platform documentation: docs.synkronyx.com
• ERO product documentation: ero-docs.synkronyx.com

Information Architecture

Core Site

Target audience: platform, security, and operations teams.

Content types:

• Landing zone governance and standards
• Shared identity and access patterns
• Shared operational runbooks and support model
• Shared naming and policy baselines

Product Site (ERO)

Target audience: product engineering and delivery teams.

Content types:

• ERO architecture and implementation details
• Offline-first engine behavior and sync strategy
• Product-specific runbooks and feature contracts
• Product roadmap and backlog guidance

IaC-First Implementation

Terraform stack location:

• infra/cloudflare-docs

Provisioned resources:

• Cloudflare Pages project for core docs
• Cloudflare Pages project for ERO docs
• Custom domains for both projects
• DNS records for both custom domains

Operating Model

1. Author docs in repository markdown.
2. Merge to main branch.
3. Cloudflare Pages deploys from GitHub integration.
4. Docs become available under custom domains.
5. Azure DevOps wiki home page links users to published docs.

Search and Discoverability Requirements

• Persistent left navigation and consistent section hierarchy
• Full-text client search enabled on both sites
• Stable page URLs and clear page titles
• Metadata and sitemap generation for indexing

Quality Gates

• Markdown lint on pull requests
• Broken-link checks on pull requests
• Preview deployments for pull requests
• Required review for architecture and security document changes

Phased Delivery

Phase 1: Platform Provisioning (Complete)

• Terraform scaffold created for Cloudflare docs projects, domains, and DNS.

Phase 2: Static Site Pipeline (Complete)

• VitePress pipeline added for searchable docs UX.
• Deterministic build scripts added for core and ERO outputs.

Phase 3: CI/CD Hardening (Next)

• Add pull request previews, lint, and link validation gates.
• Add deployment observability and runbook updates.

Ownership Model

• Core docs owner: Platform team
• Product docs owner: ERO product team
• Shared standards owner: Architecture and governance