PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/z-archive/training/handover_naming_convention.md

12 KiB
Raw Blame History

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)