wiki/training/handover_naming_convention.md

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)