michaelschiemer/deployment/docs/RESTRUCTURE_PROPOSAL.md

Dokumentations-Restrukturierung - Vorschlag

Aktuelle Situation

Statistiken

• Gesamt: 34 Markdown-Dateien im deployment/ Ordner
• Root-Level: 21 Markdown-Dateien direkt in deployment/
• Verlinkungen: 35 Referenzen im DOCUMENTATION_INDEX.md

Problem

• Viele Dokumentationsdateien direkt im Root (deployment/*.md)
• Mischung aus:
  • Haupt-Dokumentation (README.md, SETUP-GUIDE.md)
  • Status/Tracking (DEPLOYMENT_SUMMARY.md, DEPLOYMENT-TODO.md)
  • Test/Entwicklung (TEST_.md, GIT_.md, QUICK_TEST.md)
  • Troubleshooting (WORKFLOW-TROUBLESHOOTING.md, CI_CD_STATUS.md)
  • Logs/Historie (CLEANUP_LOG.md, CLEANUP_SUMMARY.md)
• Schwer ?berschaubar
• Konfigurationsdateien (ansible/, stacks/, gitea-runner/) vermischt mit Docs

Vorschlag: Strukturierte Dokumentation

Neue Struktur

deployment/
??? README.md                          # ? Haupt-Dokumentation (bleibt)
??? docs/                              # ?? Alle Dokumentation
?   ??? README.md                      # Dokumentations-Index (ersetzt DOCUMENTATION_INDEX.md)
?   ?
?   ??? guides/                        # ?? Anleitungen & Guides
?   ?   ??? setup-guide.md             # (SETUP-GUIDE.md)
?   ?   ??? quick-start.md             # (QUICK_START.md)
?   ?   ??? code-change-workflow.md    # (CODE_CHANGE_WORKFLOW.md)
?   ?   ??? deployment-commands.md     # (DEPLOYMENT_COMMANDS.md)
?   ?   ??? vault-password.md          # (ansible/VAULT_PASSWORD.md)
?   ?
?   ??? reference/                     # ?? Referenz-Dokumentation
?   ?   ??? application-stack.md       # (APPLICATION_STACK_DEPLOYMENT.md)
?   ?   ??? ansible-playbooks.md       # (ansible/README.md)
?   ?   ??? workflow-troubleshooting.md # (WORKFLOW-TROUBLESHOOTING.md)
?   ?
?   ??? status/                        # ?? Status & Tracking
?   ?   ??? deployment-summary.md      # (DEPLOYMENT_SUMMARY.md)
?   ?   ??? deployment-todo.md         # (DEPLOYMENT-TODO.md)
?   ?   ??? ci-cd-status.md            # (CI_CD_STATUS.md)
?   ?   ??? improvements.md            # (IMPROVEMENTS.md)
?   ?   ??? next-steps.md              # (NEXT_STEPS.md)
?   ?
?   ??? testing/                       # ?? Test-Dokumentation
?   ?   ??? test-results.md            # (TEST_RESULT.md)
?   ?   ??? git-deployment-test.md     # (GIT_DEPLOYMENT_TEST.md)
?   ?   ??? git-deployment-issue.md    # (GIT_DEPLOYMENT_ISSUE.md)
?   ?   ??? test-git-deployment.md     # (TEST_GIT_DEPLOYMENT.md)
?   ?   ??? quick-test.md              # (QUICK_TEST.md)
?   ?   ??? recommended-test-flow.md   # (RECOMMENDED_TEST_FLOW.md)
?   ?
?   ??? history/                       # ?? Logs & Historie
?       ??? cleanup-log.md             # (CLEANUP_LOG.md)
?       ??? cleanup-summary.md         # (CLEANUP_SUMMARY.md)
?
??? ansible/                           # Ansible Konfiguration
?   ??? README.md                      # ? Kurze ?bersicht, Link zu docs/reference/
?   ??? ...
?
??? stacks/                            # Docker Compose Stacks
?   ??? */README.md                    # Stack-spezifische Docs (bleiben)
?
??? gitea-runner/                      # Runner Konfiguration
    ??? README.md                      # Runner-spezifische Docs (bleibt)

Vorteile

? ?bersichtlichkeit

• Klare Trennung: Docs vs. Konfiguration
• Kategorisierung nach Zweck (Guides, Reference, Status, Tests, History)
• Einfacher zu navigieren

? Wartbarkeit

• Logische Gruppierung ?hnlicher Dokumente
• Einfaches Finden relevanter Dokumentation
• Einfachere Aktualisierung

? Klare Hierarchie

• docs/README.md als zentraler Einstiegspunkt
• deployment/README.md bleibt f?r Architektur-?bersicht
• Stack-spezifische READMEs bleiben nahe am Code

? Saubere Struktur

• Konfigurationsdateien nicht mit Docs vermischt
• Tests getrennt von Produktions-Docs
• Historie/Logs in separatem Bereich

Nachteile

?? Breaking Changes

• Alle Verlinkungen m?ssen aktualisiert werden
• Externe Referenzen (z.B. in anderen Projekten) m?ssen angepasst werden
• Git-Historie wird aufgeteilt

?? Migration-Aufwand

• 21 Dateien m?ssen verschoben werden
• Verlinkungen in vielen Dateien aktualisieren
• CI/CD Skripte k?nnten Pfade referenzieren

?? Gew?hnung

• Team muss neue Struktur lernen
• Neue Pfade m?ssen bekannt gemacht werden

Alternative: Minimale Restrukturierung

Falls die vollst?ndige Restrukturierung zu aufw?ndig ist:

Option B: Nur Root-Level aufr?umen

deployment/
??? README.md                          # Haupt-Dokumentation
??? DOCUMENTATION_INDEX.md             # Index (bleibt)
?
??? docs/                              # Nur Root-Level Docs verschieben
?   ??? guides/
?   ?   ??? setup-guide.md
?   ?   ??? quick-start.md
?   ?   ??? code-change-workflow.md
?   ?
?   ??? status/
?   ?   ??? deployment-summary.md
?   ?   ??? deployment-todo.md
?   ?   ??? ci-cd-status.md
?   ?
?   ??? tests/                         # Test-Dokumentation
?       ??? test-results.md
?       ??? ...
?
??? ansible/                           # Bleibt wie es ist
?   ??? README.md
?
??? stacks/                            # Bleibt wie es ist

Vorteile:

• Weniger Breaking Changes
• Schneller umzusetzen
• Hauptproblem (Root-Level Unordnung) gel?st

Nachteile:

• Keine vollst?ndige Strukturierung
• Stack-Docs bleiben verstreut

Empfehlung

F?r jetzt: Option B (Minimal)

1. ? Schnell umsetzbar
2. ? L?sen des Hauptproblems (21 Root-Level Dateien)
3. ? Minimal invasive ?nderungen
4. ? Stack-Docs bleiben nahe am Code (gut!)

Sp?ter: Option A (Vollst?ndig) wenn:

• Mehr Zeit f?r Migration vorhanden
• Automatisierung f?r Link-Updates verf?gbar
• Team w?chst und bessere Struktur ben?tigt

Migration-Plan (Option B)

Phase 1: Docs-Ordner erstellen

mkdir -p deployment/docs/{guides,status,tests}

Phase 2: Dateien verschieben

# Guides
mv SETUP-GUIDE.md docs/guides/setup-guide.md
mv QUICK_START.md docs/guides/quick-start.md
mv CODE_CHANGE_WORKFLOW.md docs/guides/code-change-workflow.md
mv DEPLOYMENT_COMMANDS.md docs/guides/deployment-commands.md
mv ansible/VAULT_PASSWORD.md docs/guides/vault-password.md

# Status
mv DEPLOYMENT_SUMMARY.md docs/status/deployment-summary.md
mv DEPLOYMENT-TODO.md docs/status/deployment-todo.md
mv CI_CD_STATUS.md docs/status/ci-cd-status.md
mv IMPROVEMENTS.md docs/status/improvements.md
mv NEXT_STEPS.md docs/status/next-steps.md

# Tests
mv TEST_RESULT.md docs/tests/test-results.md
mv GIT_DEPLOYMENT_TEST.md docs/tests/git-deployment-test.md
mv GIT_DEPLOYMENT_ISSUE.md docs/tests/git-deployment-issue.md
mv TEST_GIT_DEPLOYMENT.md docs/tests/test-git-deployment.md
mv QUICK_TEST.md docs/tests/quick-test.md
mv RECOMMENDED_TEST_FLOW.md docs/tests/recommended-test-flow.md

# Reference (optional, kann auch bleiben)
mv APPLICATION_STACK_DEPLOYMENT.md docs/reference/application-stack.md
mv WORKFLOW-TROUBLESHOOTING.md docs/reference/workflow-troubleshooting.md

# History (optional)
mv CLEANUP_LOG.md docs/history/cleanup-log.md
mv CLEANUP_SUMMARY.md docs/history/cleanup-summary.md

Phase 3: Verlinkungen aktualisieren

• DOCUMENTATION_INDEX.md aktualisieren
• README.md Verlinkungen pr?fen
• Interne Links in Dokumenten pr?fen
• CI/CD Skripte pr?fen

Phase 4: README.md erstellen

• docs/README.md als neuen Index erstellen
• DOCUMENTATION_INDEX.md ? docs/README.md migrieren

Entscheidung ben?tigt

Frage: Soll die Dokumentation restrukturiert werden?

• ? Ja, Option B (Minimal) - Nur Root-Level aufr?umen
• ? Ja, Option A (Vollst?ndig) - Komplette Restrukturierung
• ? Nein - Behalten wie es ist

Empfehlung: Option B f?r jetzt, Option A sp?ter wenn n?tig.