michaelschiemer/docs/contributing/documentation.md

Dokumentations-Anleitung

Diese Anleitung beschreibt, wie Sie zur Dokumentation des Frameworks beitragen können. Eine gute Dokumentation ist entscheidend für die Benutzerfreundlichkeit und Wartbarkeit des Frameworks.

Überblick über die Dokumentationsstruktur

Die Dokumentation des Frameworks ist in mehrere Bereiche unterteilt:

docs/
├── README.md                      # Übersicht und Navigationshilfe
├── getting-started/               # Einstiegsdokumentation
│   ├── installation.md            # Installationsanleitung
│   ├── configuration.md           # Konfigurationsanleitung
│   └── first-steps.md             # Erste Schritte mit dem Framework
├── architecture/                  # Architektur-Dokumentation
│   ├── overview.md                # Architekturübersicht
│   ├── components.md              # Hauptkomponenten
│   └── patterns.md                # Verwendete Entwurfsmuster
├── components/                    # Komponentendokumentation
│   ├── analytics/                 # Analytics-Komponente
│   │   ├── index.md               # Übersicht
│   │   ├── configuration.md       # Konfiguration
│   │   └── examples.md            # Beispiele
│   ├── validation/                # Validierungs-Komponente
│   │   ├── index.md               # Übersicht
│   │   ├── rules.md               # Validierungsregeln
│   │   └── examples.md            # Beispiele
│   ├── security/                  # Sicherheits-Komponente
│   │   ├── index.md               # Übersicht
│   │   ├── csrf-protection.md     # CSRF-Schutz im Detail
│   │   ├── security-headers.md    # Security Headers und CSP
│   │   └── request-signing.md     # Request Signing API
│   ├── waf/                       # WAF-Komponente
│   │   ├── index.md               # Übersicht
│   │   ├── machine-learning.md    # ML-Funktionalität
│   │   └── configuration.md       # Konfiguration
│   └── ...                        # Weitere Komponenten
├── guides/                        # Entwickleranleitungen
│   ├── routing.md                 # Routing-Anleitung
│   ├── controllers.md             # Controller-Anleitung
│   ├── validation.md              # Validierungs-Anleitung
│   ├── security.md                # Sicherheits-Anleitung
│   └── ...                        # Weitere Anleitungen
├── api/                           # API-Dokumentation
│   ├── index.md                   # API-Übersicht
│   └── ...                        # Generierte API-Docs
├── contributing/                  # Beitragsrichtlinien
│   ├── code-style.md              # Coding-Standards
│   ├── pull-requests.md           # PR-Prozess
│   └── documentation.md           # Dokumentationsrichtlinien
└── roadmap/                       # Projektplanung
    ├── features.md                # Feature-Tracking
    ├── tasks.md                   # Task-Tracking
    └── milestones.md              # Meilensteine

Dokumentationsstandards

Markdown-Format

Die gesamte Dokumentation wird in Markdown geschrieben. Hier sind die grundlegenden Formatierungsregeln:

Überschriften

Verwenden Sie # für Überschriften, mit einer Hierarchie von # (Hauptüberschrift) bis ###### (Überschrift der sechsten Ebene):

# Hauptüberschrift (H1)
## Überschrift der zweiten Ebene (H2)
### Überschrift der dritten Ebene (H3)
#### Überschrift der vierten Ebene (H4)
##### Überschrift der fünften Ebene (H5)
###### Überschrift der sechsten Ebene (H6)

Textformatierung

*Kursiver Text* oder _Kursiver Text_
**Fetter Text** oder __Fetter Text__
***Fett und kursiv*** oder ___Fett und kursiv___
~~Durchgestrichen~~

Listen

Ungeordnete Listen:

- Element 1
- Element 2
  - Unterelement 2.1
  - Unterelement 2.2
- Element 3

Geordnete Listen:

1. Erster Schritt
2. Zweiter Schritt
   1. Unterschritt 2.1
   2. Unterschritt 2.2
3. Dritter Schritt

Links

[Link-Text](URL)
[Link zu einer anderen Dokumentationsseite](../pfad/zur/datei.md)
[Link zu einem Abschnitt in derselben Datei](#abschnitt-id)

Bilder

![Alternativer Text](URL-zum-Bild)

Codeblöcke

Für Inline-Code:

`Inline-Code`

Für Codeblöcke:

```php
// PHP-Code hier
$variable = 'Wert';
echo $variable;
```

Unterstützte Sprachen für Syntax-Highlighting:

• php für PHP-Code
• js oder javascript für JavaScript-Code
• html für HTML-Code
• css für CSS-Code
• bash oder shell für Shell-Befehle
• json für JSON-Daten
• xml für XML-Daten
• sql für SQL-Abfragen

Tabellen

| Spalte 1 | Spalte 2 | Spalte 3 |
|----------|----------|----------|
| Zelle 1  | Zelle 2  | Zelle 3  |
| Zelle 4  | Zelle 5  | Zelle 6  |

Blockzitate

> Dies ist ein Blockzitat.
> Es kann mehrere Zeilen umfassen.

Horizontale Linien

---

Dokumentationsstruktur

Jede Dokumentationsdatei sollte die folgende Struktur haben:

1. Hauptüberschrift: Der Titel des Dokuments als H1-Überschrift (#).
2. Einführung: Eine kurze Einführung, die den Zweck und Umfang des Dokuments beschreibt.
3. Hauptinhalt: Der Hauptinhalt des Dokuments, organisiert in Abschnitte mit H2-Überschriften (##).
4. Beispiele: Praktische Beispiele, die die Verwendung der beschriebenen Funktionalität demonstrieren.
5. Weitere Informationen: Links zu verwandten Dokumenten oder externen Ressourcen.

Schreibstil

• Verwenden Sie eine klare, präzise und konsistente Sprache.
• Schreiben Sie in der zweiten Person ("Sie können..." statt "Man kann...").
• Verwenden Sie die aktive Stimme statt der passiven Stimme.
• Halten Sie Sätze und Absätze kurz und fokussiert.
• Verwenden Sie Aufzählungslisten für Schritte oder Optionen.
• Erklären Sie Fachbegriffe, wenn sie zum ersten Mal verwendet werden.
• Vermeiden Sie Jargon und Abkürzungen, es sei denn, sie sind allgemein bekannt oder wurden erklärt.

Beispiele

Gute Beispiele sind ein wesentlicher Bestandteil der Dokumentation. Jedes Beispiel sollte:

• Realistisch und praxisnah sein
• Vollständig und funktionsfähig sein
• Gut kommentiert sein, um zu erklären, was passiert
• Die empfohlenen Praktiken und Coding-Standards befolgen

Beitragen zur Dokumentation

Neue Dokumentation erstellen

Wenn Sie neue Dokumentation erstellen möchten:

1. Identifizieren Sie den Bereich, in dem die Dokumentation benötigt wird.
2. Erstellen Sie eine neue Markdown-Datei im entsprechenden Verzeichnis.
3. Folgen Sie der oben beschriebenen Dokumentationsstruktur.
4. Fügen Sie die neue Datei in die Navigation ein, indem Sie Links in verwandten Dokumenten hinzufügen.

Bestehende Dokumentation aktualisieren

Wenn Sie bestehende Dokumentation aktualisieren möchten:

1. Identifizieren Sie die zu aktualisierende Datei.
2. Nehmen Sie die erforderlichen Änderungen vor, wobei Sie die Dokumentationsstandards einhalten.
3. Aktualisieren Sie alle Links oder Verweise, die durch Ihre Änderungen betroffen sein könnten.

Pull Request-Prozess für Dokumentation

Der Prozess für das Einreichen von Dokumentationsänderungen ist derselbe wie für Code-Änderungen:

1. Erstellen Sie einen Feature-Branch für Ihre Änderungen.
2. Nehmen Sie die Änderungen vor.
3. Reichen Sie einen Pull Request ein.
4. Reagieren Sie auf Feedback und nehmen Sie bei Bedarf weitere Änderungen vor.

Weitere Informationen finden Sie in der Pull Request-Anleitung.

Dokumentation generieren

API-Dokumentation

Die API-Dokumentation wird automatisch aus dem Quellcode generiert. Um die API-Dokumentation zu generieren:

php console.php docs:generate-api

Dies generiert die API-Dokumentation im Verzeichnis docs/api/.

Dokumentation lokal anzeigen

Um die Dokumentation lokal anzuzeigen, können Sie einen Markdown-Viewer oder einen lokalen Webserver verwenden:

# Mit PHP-Webserver
php -S localhost:8000 -t docs

# Mit Node.js und docsify
npm install -g docsify-cli
docsify serve docs

Dokumentations-Checkliste

Verwenden Sie diese Checkliste, um sicherzustellen, dass Ihre Dokumentation vollständig und von hoher Qualität ist:

• Die Dokumentation folgt der standardisierten Struktur.
• Die Hauptüberschrift beschreibt klar den Inhalt des Dokuments.
• Die Einführung erklärt den Zweck und Umfang des Dokuments.
• Alle Fachbegriffe werden erklärt oder verlinkt.
• Die Dokumentation enthält praktische Beispiele.
• Die Beispiele sind vollständig, funktionsfähig und gut kommentiert.
• Die Dokumentation enthält Links zu verwandten Dokumenten.
• Die Dokumentation ist frei von Rechtschreib- und Grammatikfehlern.
• Die Formatierung ist konsistent und folgt den Markdown-Standards.
• Die Dokumentation ist aktuell und spiegelt den aktuellen Stand des Codes wider.

Tipps für gute Dokumentation

Benutzerorientierung

Denken Sie immer an die Benutzer Ihrer Dokumentation:

• Wer sind sie? (Anfänger, erfahrene Entwickler, Mitwirkende)
• Was wollen sie erreichen?
• Welche Vorkenntnisse haben sie?

Passen Sie Ihre Dokumentation entsprechend an.

Klare Struktur

Eine klare Struktur hilft den Benutzern, die benötigten Informationen schnell zu finden:

• Verwenden Sie aussagekräftige Überschriften.
• Gruppieren Sie verwandte Informationen.
• Verwenden Sie Aufzählungslisten und Tabellen, um Informationen zu organisieren.
• Fügen Sie ein Inhaltsverzeichnis für längere Dokumente hinzu.

Visuelle Elemente

Visuelle Elemente können die Dokumentation verbessern:

• Verwenden Sie Diagramme, um komplexe Beziehungen zu erklären.
• Fügen Sie Screenshots hinzu, um Benutzeroberflächen zu zeigen.
• Verwenden Sie Codebeispiele, um Konzepte zu demonstrieren.

Kontinuierliche Verbesserung

Dokumentation ist nie "fertig":

• Überprüfen Sie regelmäßig die Dokumentation auf Aktualität.
• Berücksichtigen Sie Feedback von Benutzern.
• Aktualisieren Sie die Dokumentation, wenn sich der Code ändert.

Häufige Probleme und Lösungen

Veraltete Dokumentation

Problem: Die Dokumentation spiegelt nicht den aktuellen Stand des Codes wider.

Lösung:

• Überprüfen Sie die Dokumentation regelmäßig.
• Aktualisieren Sie die Dokumentation als Teil des Entwicklungsprozesses.
• Verwenden Sie automatisierte Tools, um Inkonsistenzen zu erkennen.

Unvollständige Dokumentation

Problem: Die Dokumentation deckt nicht alle Aspekte der Funktionalität ab.

Lösung:

• Identifizieren Sie fehlende Bereiche durch Benutzerfeedback.
• Erstellen Sie eine Checkliste der zu dokumentierenden Funktionen.
• Priorisieren Sie die Dokumentation basierend auf der Benutzerrelevanz.

Unklare Dokumentation

Problem: Die Dokumentation ist schwer zu verstehen oder zu technisch.

Lösung:

• Verwenden Sie einfache, klare Sprache.
• Erklären Sie Fachbegriffe.
• Fügen Sie Beispiele hinzu, um Konzepte zu verdeutlichen.
• Lassen Sie die Dokumentation von jemandem überprüfen, der mit dem Thema nicht vertraut ist.

Weitere Informationen

• Markdown-Anleitung: Eine umfassende Anleitung zu Markdown.
• Technisches Schreiben: Google's Anleitung zum technischen Schreiben.
• Dokumentationstools: Tools für die Erstellung und Verwaltung von Dokumentation.
• Coding Standards: Erfahren Sie mehr über die Coding Standards des Projekts.
• Pull Request-Anleitung: Erfahren Sie, wie Sie Pull Requests erstellen und überprüfen.
• Architekturübersicht: Überblick über die Architektur des Frameworks.