Warning
🚧 Work in Progress: This page is currently under construction. Content may be incomplete or subject to change. To contribute, see the contribution guide.
ADR-003: Documentation Portal — MkDocs + Azure Static Web Apps
| Field | Value |
|---|---|
| Status | ✅ Accepted |
| Date | 2025 |
| Decision makers | CTO / CDO |
Context
The Technology department had no centralized technical documentation repository. Knowledge was scattered across emails, outdated wikis, and local files, making onboarding, support, and knowledge transfer difficult.
Decision
Adopt MkDocs Material as the static documentation generator, with a private GitHub repository, a build pipeline via GitHub Actions, hosted on Azure Static Web Apps (Free tier), with Entra ID authentication and AD security group access control.
Rationale
- Docs as code: documentation versioned alongside systems in GitHub
- MkDocs Material: best plugin ecosystem for technical docs, native search, Mermaid support
- Azure Static Web Apps: native Entra ID integration, free SSL and CDN on the Free tier
- No hosting cost for the MVP
- GitHub Actions already used by the division for CI/CD
Alternatives considered
| Alternative | Why it was not chosen |
|---|---|
| Confluence | Licensing cost; not docs as code |
| GitHub Pages | No native access control without GitHub Enterprise Cloud |
| Notion | No native Entra ID integration; limited access control |
| SharePoint | Poor editing experience for technical docs; not docs as code |
Consequences
- All technical documentation must be created and maintained in this portal
- Each squad owns the documentation for their systems
- Standardized templates in
/standards/templates/to ensure consistency