Zum Hauptinhalt springen

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.md in 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​

  1. Markdown as Foundation - All documentation is Markdown-based
  2. Docs as Code - Documentation lives in Git, reviewed like code
  3. Single Source of Truth - One authoritative location per topic
  4. 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 TypeLocationExamples
Project-specificProject RepoAPI Reference, Build Instructions, Local Setup
Multi-Repo Solutionsdocs/Kundenportal (4 Repos), BOAbot Integration
Standards & Guidelinesdocs/Documentation Guidelines, ADR Format
Architecture Overviewsdocs/System Context, Data Flow, Security Boundaries
External Documentationdocs/*/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​

ChannelAudienceContentAuth
Static Site (internal)TOGETHER TeamEverythingAzure AD
Customer DocsMakler ITexternal/ foldersOptional
PDF ExportAuditors, ContractsSelected docsN/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​

  1. Review dieses Proposals
  2. Open Questions klΓ€ren
  3. Bei Akzeptanz β†’ decisions/ADR-001-documentation-strategy.md
  4. Publishing Pipeline aufsetzen

References​