224 lines
7.5 KiB
Markdown
224 lines
7.5 KiB
Markdown
# 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.
|