ADR-0001 — Documentation tooling and structure¶
Date: 2026-09-01 · Status: accepted
Context¶
The project starts with no mandated documentation tool. We need complete documentation, with diagrams and screenshots, that can be handed over to colleagues and exported to PDF.
Decision¶
MkDocs + Material theme, Markdown content, structured according to
arc42, complemented by step-by-step guides and ADRs. Diagrams as
inline Mermaid. PDF export via the print-site plugin.
Rejected alternatives¶
| Alternative | Why rejected |
|---|---|
| AsciiDoc + Antora + PlantUML | More powerful but heavier to install and maintain; Markdown is more widely shared |
| Astro Starlight | Depends on Node.js; oriented towards websites rather than architecture documentation |
| Corporate wiki (Confluence, etc.) | None is mandated today; the Markdown will migrate easily if a tool is chosen later |
| draw.io diagrams / images | Binary or manual export, not diffable; Mermaid is versioned text |
Consequences¶
- Documentation versioned with the code, reviewed by diff.
- A single tool to install (
pip install -r requirements.txt). - Mermaid diagrams are limited to the supported types (flowchart, sequence, class, state, ER, gantt) — sufficient for arc42.
- Migration to another tool remains possible without rewriting the content.