chore: sync staging workspace
This commit is contained in:
223
deployment/docs/RESTRUCTURE_PROPOSAL.md
Normal file
223
deployment/docs/RESTRUCTURE_PROPOSAL.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# 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
|
||||
```bash
|
||||
mkdir -p deployment/docs/{guides,status,tests}
|
||||
```
|
||||
|
||||
### Phase 2: Dateien verschieben
|
||||
```bash
|
||||
# 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.
|
||||
Reference in New Issue
Block a user