# 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)