478 lines
12 KiB
Markdown
478 lines
12 KiB
Markdown
# Naming Convention für Wiki-Dokumentation (ALS IDEE FÜR STEPHAN - NICHT ANGEWENDET - SO KURZ WIE MÖGLICH)
|
|
|
|
**Zweck:** Klare Strukturierung und Auffindbarkeit aller Dokumente im Wiki
|
|
|
|
---
|
|
|
|
## Grundprinzipien
|
|
|
|
1. **Konsistenz**: Einheitliche Namensgebung für ähnliche Dokumente
|
|
2. **Selbsterklärend**: Dateiname sollte Inhalt und Typ erkennen lassen
|
|
3. **Kategorisierung**: Präfixe für schnelle Identifikation
|
|
4. **Versionierung**: Bei Bedarf Datum oder Version im Namen
|
|
|
|
---
|
|
|
|
## Präfix-System
|
|
|
|
### `doc_*` - Architektur- und System-Dokumentation
|
|
|
|
**Verwendung:** Architektur-Übersichten, System-Beschreibungen, High-Level-Dokumentation
|
|
|
|
**Beispiele:**
|
|
- `doc_gateway_architecture_overview.md` - Gateway-Architektur Übersicht
|
|
- `doc_gateway_development_framework.md` - Development Framework
|
|
- `doc_system_prompt_flow.md` - System: Prompt Flow
|
|
- `doc_system_polling_logic.md` - System: Polling Logic
|
|
- `doc_architecture_ai_service.html` - Architektur: AI Service
|
|
- `doc_architecture_workflow.html` - Architektur: Workflow
|
|
|
|
**Struktur:**
|
|
```
|
|
doc_[bereich]_[thema]_[detail].md
|
|
```
|
|
|
|
**Bereiche:**
|
|
- `gateway` - Gateway-spezifische Dokumentation
|
|
- `architecture` - Architektur-Dokumentation
|
|
- `system` - System-spezifische Dokumentation
|
|
- `security` - Sicherheits-Dokumentation
|
|
- `user` - User-Dokumentation
|
|
|
|
---
|
|
|
|
### `implementation_*` - Implementierungsdetails
|
|
|
|
**Verwendung:** Detaillierte Implementierungs-Beschreibungen, Refactoring-Dokumentation, Technische Details
|
|
|
|
**Beispiele:**
|
|
- `implementation_workflow_automation_architecture.md` - Workflow Automation Architektur
|
|
- `implementation_chat_validation_workflow_task_action.md` - Chat Validation Workflow
|
|
- `implementation_ui_table_pagination.md` - UI Table Pagination
|
|
- `implementation_action_validation_generic.md` - Generic Action Validation
|
|
- `implementation_content_handling_with_dynamic_ai_v2.md` - Content Handling mit Dynamic AI v2
|
|
- `implementation_refactor_stats-unified.md` - Refactoring: Stats Unified
|
|
- `implementation_refactor_db-consistency.md` - Refactoring: DB Consistency
|
|
|
|
**Struktur:**
|
|
```
|
|
implementation_[komponente]_[aspekt]_[detail].md
|
|
```
|
|
|
|
**Komponenten:**
|
|
- `workflow` - Workflow-Implementierungen
|
|
- `chat` - Chat-Implementierungen
|
|
- `ui` - UI-Implementierungen
|
|
- `action` - Action-Implementierungen
|
|
- `content` - Content-Handling
|
|
- `refactor` - Refactoring-Dokumentation
|
|
|
|
---
|
|
|
|
### `handover_*` - Handover-Dokumente
|
|
|
|
**Verwendung:** Handover-Dokumentation, Einarbeitungspläne, Wissenstransfer
|
|
|
|
**Beispiele:**
|
|
- `handover_agenda_sync.md` - Agenda für Sync-Meeting
|
|
- `handover_einarbeitungsplan.md` - Einarbeitungsplan
|
|
- `handover_naming_convention.md` - Naming Convention (dieses Dokument)
|
|
- `handover_[thema]_[detail].md`
|
|
|
|
**Struktur:**
|
|
```
|
|
handover_[thema]_[detail].md
|
|
```
|
|
|
|
---
|
|
|
|
### `spec_*` - Spezifikationen
|
|
|
|
**Verwendung:** Feature-Spezifikationen, Anforderungen, Design-Dokumente
|
|
|
|
**Beispiele:**
|
|
- `spec_workflow-implementation.md` - Workflow Implementation Spec
|
|
- `spec_workflow-architecture.md` - Workflow Architecture Spec
|
|
- `spec_ui.md` - UI Specification
|
|
- `spec_progress_logging.md` - Progress Logging Specification
|
|
|
|
**Struktur:**
|
|
```
|
|
spec_[bereich]_[thema].md
|
|
```
|
|
|
|
---
|
|
|
|
### `user_*` - User-Dokumentation
|
|
|
|
**Verwendung:** Benutzer-Anleitungen, How-To-Guides, User-Facing-Dokumentation
|
|
|
|
**Beispiele:**
|
|
- `user_applikation.md` - User: Applikation
|
|
- `user_kunden.md` - User: Kunden
|
|
- `user_partner.md` - User: Partner
|
|
- `user_investoren.md` - User: Investoren
|
|
- `user_product.md` - User: Product
|
|
- `user_summary.md` - User: Summary
|
|
|
|
**Struktur:**
|
|
```
|
|
user_[zielgruppe]_[thema].md
|
|
```
|
|
|
|
---
|
|
|
|
### `security_*` - Sicherheits-Dokumentation
|
|
|
|
**Verwendung:** Sicherheits-Richtlinien, Key Management, Zugriffskontrollen
|
|
|
|
**Beispiele:**
|
|
- `security_key_management.md` - Key Management
|
|
- `security_role_based_access.md` - Role-Based Access Control
|
|
- `security-migration-guide.md` - Security Migration Guide
|
|
|
|
**Struktur:**
|
|
```
|
|
security_[thema]_[detail].md
|
|
```
|
|
|
|
---
|
|
|
|
### `prompt_*` - Prompt-Dokumentation
|
|
|
|
**Verwendung:** Prompt-Templates, Prompt-Engineering, AI-Prompt-Dokumentation
|
|
|
|
**Beispiele:**
|
|
- `prompt_produce_diagrams.md` - Prompt: Diagramme produzieren
|
|
|
|
**Struktur:**
|
|
```
|
|
prompt_[zweck]_[detail].md
|
|
```
|
|
|
|
---
|
|
|
|
## Dateiformate
|
|
|
|
### Markdown (`.md`)
|
|
**Standard-Format** für alle Text-Dokumentation
|
|
- Einfach zu bearbeiten
|
|
- Versionierbar
|
|
- Gut lesbar in GitHub
|
|
|
|
### HTML (`.html`)
|
|
**Für komplexe Visualisierungen**
|
|
- Interaktive Diagramme
|
|
- Erweiterte Formatierung
|
|
- Wenn Markdown nicht ausreicht
|
|
|
|
### PDF (`.pdf`)
|
|
**Für finale Dokumente**
|
|
- Präsentationen
|
|
- Externe Dokumentation
|
|
- Druck-Versionen
|
|
|
|
### Draw.io (`.drawio`)
|
|
**Für Diagramme**
|
|
- Architektur-Diagramme
|
|
- Flowcharts
|
|
- Komponenten-Diagramme
|
|
|
|
### Mermaid (`.mermaid`)
|
|
**Für Code-basierte Diagramme**
|
|
- Versionierbare Diagramme
|
|
- Einfach zu aktualisieren
|
|
- In Markdown integrierbar
|
|
|
|
---
|
|
|
|
## Verzeichnisstruktur
|
|
|
|
### `wiki/appdoc/` - Architektur-Dokumentation
|
|
**Inhalt:**
|
|
- `doc_*` - Architektur- und System-Dokumentation
|
|
- `user_*` - User-Dokumentation
|
|
- `spec_*` - Spezifikationen
|
|
- `security_*` - Sicherheits-Dokumentation
|
|
- `prompt_*` - Prompt-Dokumentation
|
|
|
|
**Beispiele:**
|
|
- `doc_gateway_architecture_overview.md`
|
|
- `doc_system_prompt_flow.md`
|
|
- `user_applikation.md`
|
|
- `spec_ui.md`
|
|
- `security_key_management.md`
|
|
|
|
---
|
|
|
|
### `wiki/implementation/` - Implementierungsdetails
|
|
**Inhalt:**
|
|
- `implementation_*` - Implementierungs-Dokumentation
|
|
- `security-migration-guide.md` - Migration Guides
|
|
|
|
**Beispiele:**
|
|
- `implementation_workflow_automation_architecture.md`
|
|
- `implementation_chat_validation_workflow_task_action.md`
|
|
- `implementation_refactor_stats-unified.md`
|
|
|
|
---
|
|
|
|
### `wiki/deployment/` - Deployment-Informationen
|
|
**Inhalt:**
|
|
- Deployment-Diagramme
|
|
- Instanzenübersicht
|
|
- Deployment-Anleitungen
|
|
- Secrets-Management
|
|
|
|
**Beispiele:**
|
|
- `Instanzenübersicht.drawio`
|
|
- `Instanzenübersicht.svg`
|
|
- `poweron_sec.kdbx`
|
|
|
|
---
|
|
|
|
### `wiki/training/` - Handover & Training
|
|
**Inhalt:**
|
|
- `handover_*` - Handover-Dokumente
|
|
- Einarbeitungspläne
|
|
- Training-Materialien
|
|
|
|
**Beispiele:**
|
|
- `handover_agenda_sync.md`
|
|
- `handover_einarbeitungsplan.md`
|
|
- `handover_naming_convention.md`
|
|
|
|
---
|
|
|
|
### `wiki/reviews/` - Code-Reviews & Analysen
|
|
**Inhalt:**
|
|
- Code-Review-Dokumente
|
|
- Analysen
|
|
- Reports
|
|
|
|
**Beispiele:**
|
|
- `context_checker_analysis.md`
|
|
- `report_20251020_unused_functions_analysis.md`
|
|
- `report_20251020_workflow_step_by_step_analysis.md`
|
|
|
|
---
|
|
|
|
### `wiki/strategy/` - Strategische Dokumente
|
|
**Inhalt:**
|
|
- Produktstrategie
|
|
- Marketing-Materialien
|
|
- Strategische Planung
|
|
|
|
**Beispiele:**
|
|
- `doc_produktestrategie.md`
|
|
- `doc_playground_marketing_pitch.md`
|
|
|
|
---
|
|
|
|
### `wiki/archiv/` - Archivierte Dokumente
|
|
**Inhalt:**
|
|
- Alte Dokumente
|
|
- Historische Versionen
|
|
- Nicht mehr aktive Dokumente
|
|
|
|
**Naming:** Keine spezielle Convention, aber Datum im Namen empfohlen
|
|
- `2025-07_chat_process_visualization.md`
|
|
- `poweron_summary_202404.md`
|
|
|
|
---
|
|
|
|
## Namenskonventionen im Detail
|
|
|
|
### Allgemeine Regeln
|
|
|
|
1. **Kleinbuchstaben**: Alle Dateinamen in Kleinbuchstaben
|
|
2. **Unterstriche**: Wörter mit `_` trennen (nicht `-`)
|
|
3. **Keine Leerzeichen**: Niemals Leerzeichen verwenden
|
|
4. **Keine Sonderzeichen**: Keine Umlaute, Sonderzeichen außer `_`, `-`, `.`
|
|
5. **Datum**: Wenn nötig, Format `YYYYMMDD` oder `YYYY-MM-DD`
|
|
|
|
### Präfix + Thema + Detail
|
|
|
|
**Format:**
|
|
```
|
|
[präfix]_[bereich]_[thema]_[detail].[extension]
|
|
```
|
|
|
|
**Beispiele:**
|
|
- `doc_gateway_architecture_overview.md` ✅
|
|
- `implementation_workflow_automation_architecture.md` ✅
|
|
- `handover_agenda_sync.md` ✅
|
|
- `spec_ui.md` ✅
|
|
|
|
**Nicht:**
|
|
- `Gateway Architecture Overview.md` ❌ (Leerzeichen, Großbuchstaben)
|
|
- `doc-gateway-architecture-overview.md` ❌ (Bindestriche statt Unterstriche)
|
|
- `DocGatewayArchitectureOverview.md` ❌ (CamelCase, kein Präfix)
|
|
|
|
---
|
|
|
|
## Versionierung
|
|
|
|
### Option 1: Datum im Namen
|
|
**Format:** `[präfix]_[thema]_[YYYYMMDD].md`
|
|
|
|
**Beispiele:**
|
|
- `doc_investor_20251014.md`
|
|
- `report_20251020_unused_functions_analysis.md`
|
|
|
|
### Option 2: Versionsnummer
|
|
**Format:** `[präfix]_[thema]_v[version].md`
|
|
|
|
**Beispiele:**
|
|
- `implementation_content_handling_with_dynamic_ai_v2.md`
|
|
- `spec_workflow_v1.md`
|
|
|
|
### Option 3: Keine Versionierung
|
|
Für aktuelle Dokumente, die kontinuierlich aktualisiert werden.
|
|
|
|
---
|
|
|
|
## Dateierweiterungen
|
|
|
|
### `.md` - Markdown (Standard)
|
|
**Verwendung:** Alle Text-Dokumentation
|
|
|
|
### `.html` - HTML
|
|
**Verwendung:** Komplexe Visualisierungen, interaktive Inhalte
|
|
|
|
### `.pdf` - PDF
|
|
**Verwendung:** Finale Dokumente, Präsentationen, externe Dokumentation
|
|
|
|
### `.drawio` - Draw.io Diagramme
|
|
**Verwendung:** Architektur-Diagramme, Flowcharts
|
|
|
|
### `.mermaid` - Mermaid Diagramme
|
|
**Verwendung:** Code-basierte Diagramme, versionierbare Diagramme
|
|
|
|
### `.svg` - SVG Diagramme
|
|
**Verwendung:** Exportierte Diagramme, Vektorgrafiken
|
|
|
|
---
|
|
|
|
## Beispiele für verschiedene Dokumenttypen
|
|
|
|
### Architektur-Dokumentation
|
|
```
|
|
doc_gateway_architecture_overview.md
|
|
doc_architecture_ai_service.html
|
|
doc_architecture_workflow.html
|
|
doc_system_prompt_flow.md
|
|
doc_system_polling_logic.md
|
|
```
|
|
|
|
### Implementierungs-Dokumentation
|
|
```
|
|
implementation_workflow_automation_architecture.md
|
|
implementation_chat_validation_workflow_task_action.md
|
|
implementation_ui_table_pagination.md
|
|
implementation_refactor_stats-unified.md
|
|
```
|
|
|
|
### User-Dokumentation
|
|
```
|
|
user_applikation.md
|
|
user_kunden.md
|
|
user_partner.md
|
|
user_investoren.md
|
|
user_product.md
|
|
```
|
|
|
|
### Spezifikationen
|
|
```
|
|
spec_workflow-implementation.md
|
|
spec_workflow-architecture.md
|
|
spec_ui.md
|
|
spec_progress_logging.md
|
|
```
|
|
|
|
### Handover-Dokumentation
|
|
```
|
|
handover_agenda_sync.md
|
|
handover_einarbeitungsplan.md
|
|
handover_naming_convention.md
|
|
```
|
|
|
|
### Sicherheits-Dokumentation
|
|
```
|
|
security_key_management.md
|
|
security_role_based_access.md
|
|
security-migration-guide.md
|
|
```
|
|
|
|
---
|
|
|
|
## Checkliste für neue Dokumente
|
|
|
|
Vor dem Erstellen eines neuen Dokuments:
|
|
|
|
- [ ] Richtigen Präfix gewählt? (`doc_`, `implementation_`, `handover_`, etc.)
|
|
- [ ] Richtiges Verzeichnis gewählt? (`appdoc/`, `implementation/`, `training/`, etc.)
|
|
- [ ] Konsistente Namensgebung? (Kleinbuchstaben, Unterstriche)
|
|
- [ ] Selbsterklärender Name? (Inhalt erkennbar)
|
|
- [ ] Richtige Dateierweiterung? (`.md` für Standard, `.html` für komplexe Inhalte)
|
|
- [ ] Keine Duplikate? (Bestehende Dokumente prüfen)
|
|
|
|
---
|
|
|
|
## Migration bestehender Dokumente
|
|
|
|
### Schritt 1: Kategorisierung
|
|
- Alle Dokumente durchgehen
|
|
- Präfix zuordnen
|
|
- Verzeichnis zuordnen
|
|
|
|
### Schritt 2: Umbenennung
|
|
- Dateinamen anpassen
|
|
- Konsistente Namensgebung
|
|
- Verzeichnis verschieben falls nötig
|
|
|
|
### Schritt 3: Verlinkungen aktualisieren
|
|
- Interne Links aktualisieren
|
|
- Referenzen aktualisieren
|
|
- Index aktualisieren
|
|
|
|
### Schritt 4: Dokumentation
|
|
- Änderungen dokumentieren
|
|
- Migration-Plan erstellen
|
|
- Team informieren
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **Konsistenz**: Immer die gleiche Namensgebung verwenden
|
|
2. **Selbsterklärend**: Dateiname sollte Inhalt erkennen lassen
|
|
3. **Kategorisierung**: Präfixe für schnelle Identifikation
|
|
4. **Versionierung**: Bei Bedarf Datum oder Version im Namen
|
|
5. **Verzeichnisstruktur**: Dokumente im richtigen Verzeichnis ablegen
|
|
6. **Dokumentation**: Änderungen dokumentieren
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
### Q: Was wenn ein Dokument in mehrere Kategorien passt?
|
|
**A:** Hauptkategorie wählen, andere im Dokument erwähnen. Bei Bedarf Verlinkungen erstellen.
|
|
|
|
### Q: Was wenn ein Dokument keinen passenden Präfix hat?
|
|
**A:** Neuen Präfix vorschlagen und dokumentieren. Konsistenz ist wichtig.
|
|
|
|
### Q: Soll ich bestehende Dokumente umbenennen?
|
|
**A:** Schrittweise, wenn sinnvoll. Nicht alles auf einmal, sondern bei Gelegenheit.
|
|
|
|
### Q: Was mit sehr langen Dateinamen?
|
|
**A:** Prägnant bleiben, aber selbsterklärend. Abkürzungen vermeiden, wenn möglich.
|
|
|
|
### Q: Soll ich Datum oder Versionsnummer verwenden?
|
|
**A:** Datum für Reports/Analysen, Versionsnummer für Features/Specs, keine Versionierung für aktuelle Dokumente.
|
|
|
|
---
|
|
|
|
**Letzte Aktualisierung:** [Datum]
|
|
**Verantwortlich:** Stephan (Dokumentation & Struktur)
|
|
|