Proposal: Documentation Strategy
π€ Generated with Claude Code
β οΈ Not yet reviewed
Co-Authored-By: Claude (noreply@anthropic.com)
Status: Draft Date: 2025-12
Partly implemented. The hub-and-spoke model and the "what goes where" rules from this proposal are now in effect and documented in
DOCUMENTATION-GUIDELINES.mdin the repository root, which is authoritative. Where the two differ, the guideline wins. This document remains as the record of the reasoning.
Summaryβ
Definition einer Dokumentationsstrategie fΓΌr TOGETHER CCA basierend auf Hub-and-Spoke Modell mit Markdown als Grundlage.
Motivationβ
- Externe Reviews (Atos 2024) empfehlen bessere Architekturdokumentation
- Dokumentation ist ΓΌber mehrere Repos verteilt
- Keine klare Strategie fΓΌr Multi-Repo Solutions
- Kein Publishing-Workflow
Proposed Principlesβ
- Markdown as Foundation - All documentation is Markdown-based
- Docs as Code - Documentation lives in Git, reviewed like code
- Single Source of Truth - One authoritative location per topic
- Multiple Channels - Same source, different outputs
Repository Model (Hub-and-Spoke)β
docs/ (Hub) Project Repos (Spokes)
βββ Γbersichten βββ cca.kundenportal/docs/
βββ Cross-Repo Solutions βββ cca.endCustomerApi/docs/
βββ Guidelines & Standards βββ cca.kundenportal.managementserver/docs/
βββ Architektur-Entscheidungen βββ tis.identity/docs/
What Goes Whereβ
| Content Type | Location | Examples |
|---|---|---|
| Project-specific | Project Repo | API Reference, Build Instructions, Local Setup |
| Multi-Repo Solutions | docs/ | Kundenportal (4 Repos), BOAbot Integration |
| Standards & Guidelines | docs/ | Documentation Guidelines, ADR Format |
| Architecture Overviews | docs/ | System Context, Data Flow, Security Boundaries |
| External Documentation | docs/*/external/ | Hosting Guide, Customer Handbooks |
Publishing Channelsβ
Markdown Source (docs/)
β
ββββΊ Static Site (internal)
β - Full documentation
β - Search, navigation
β - Auth: Azure AD
β
ββββΊ Customer Docs (external)
β - Filtered: external/ folders only
β - Hosting Guide, API Docs
β
ββββΊ PDF Export
β - On-demand generation
β - For offline/contractual use
β
ββββΊ IDE Integration
- README.md in repos
- CLAUDE.md for AI assistants
Channel Matrixβ
| Channel | Audience | Content | Auth |
|---|---|---|---|
| Static Site (internal) | TOGETHER Team | Everything | Azure AD |
| Customer Docs | Makler IT | external/ folders | Optional |
| PDF Export | Auditors, Contracts | Selected docs | N/A |
Folder Structureβ
docs/
βββ _plans.md # Roadmap
βββ README.md # Structure overview
βββ proposals/ # Open proposals (like this one)
β
βββ products/ # Product Documentation
β βββ cca/
β βββ kundenportal/
β βββ _plans.md
β βββ proposals/
β βββ decisions/ # Accepted ADRs
β βββ external/
β
βββ development/ # Development Guidelines
βββ shared/
βββ documentation-guidelines.md
Open Questionsβ
- Publishing Tool: MkDocs vs. Docusaurus vs. VitePress?
- Hosting: Azure Static Web Apps vs. GitHub Pages?
- Customer Docs: Separate site oder gefilterte Version?
- Search: Algolia vs. built-in?
Next Stepsβ
- Review dieses Proposals
- Open Questions klΓ€ren
- Bei Akzeptanz β
decisions/ADR-001-documentation-strategy.md - Publishing Pipeline aufsetzen
Referencesβ
- Atos Architecture Review 2024 - Section 6.1.1
- Documentation Guidelines - Current writing standards (in development)