Enable Discovery debug logging for production troubleshooting
- Add DISCOVERY_LOG_LEVEL=debug - Add DISCOVERY_SHOW_PROGRESS=true - Temporary changes for debugging InitializerProcessor fixes on production
This commit is contained in:
345
docs/contributing/documentation.md
Normal file
345
docs/contributing/documentation.md
Normal file
@@ -0,0 +1,345 @@
|
||||
# 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):
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
*Kursiver Text* oder _Kursiver Text_
|
||||
**Fetter Text** oder __Fetter Text__
|
||||
***Fett und kursiv*** oder ___Fett und kursiv___
|
||||
~~Durchgestrichen~~
|
||||
```
|
||||
|
||||
#### Listen
|
||||
|
||||
Ungeordnete Listen:
|
||||
|
||||
```markdown
|
||||
- Element 1
|
||||
- Element 2
|
||||
- Unterelement 2.1
|
||||
- Unterelement 2.2
|
||||
- Element 3
|
||||
```
|
||||
|
||||
Geordnete Listen:
|
||||
|
||||
```markdown
|
||||
1. Erster Schritt
|
||||
2. Zweiter Schritt
|
||||
1. Unterschritt 2.1
|
||||
2. Unterschritt 2.2
|
||||
3. Dritter Schritt
|
||||
```
|
||||
|
||||
#### Links
|
||||
|
||||
```markdown
|
||||
[Link-Text](URL)
|
||||
[Link zu einer anderen Dokumentationsseite](../pfad/zur/datei.md)
|
||||
[Link zu einem Abschnitt in derselben Datei](#abschnitt-id)
|
||||
```
|
||||
|
||||
#### Bilder
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
#### Codeblöcke
|
||||
|
||||
Für Inline-Code:
|
||||
|
||||
```markdown
|
||||
`Inline-Code`
|
||||
```
|
||||
|
||||
Für Codeblöcke:
|
||||
|
||||
````markdown
|
||||
```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
|
||||
|
||||
```markdown
|
||||
| Spalte 1 | Spalte 2 | Spalte 3 |
|
||||
|----------|----------|----------|
|
||||
| Zelle 1 | Zelle 2 | Zelle 3 |
|
||||
| Zelle 4 | Zelle 5 | Zelle 6 |
|
||||
```
|
||||
|
||||
#### Blockzitate
|
||||
|
||||
```markdown
|
||||
> Dies ist ein Blockzitat.
|
||||
> Es kann mehrere Zeilen umfassen.
|
||||
```
|
||||
|
||||
#### Horizontale Linien
|
||||
|
||||
```markdown
|
||||
---
|
||||
```
|
||||
|
||||
### 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](pull-requests.md).
|
||||
|
||||
## Dokumentation generieren
|
||||
|
||||
### API-Dokumentation
|
||||
|
||||
Die API-Dokumentation wird automatisch aus dem Quellcode generiert. Um die API-Dokumentation zu generieren:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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](https://www.markdownguide.org/): Eine umfassende Anleitung zu Markdown.
|
||||
- [Technisches Schreiben](https://developers.google.com/tech-writing): Google's Anleitung zum technischen Schreiben.
|
||||
- [Dokumentationstools](https://docusaurus.io/): Tools für die Erstellung und Verwaltung von Dokumentation.
|
||||
- [Coding Standards](code-style.md): Erfahren Sie mehr über die Coding Standards des Projekts.
|
||||
- [Pull Request-Anleitung](pull-requests.md): Erfahren Sie, wie Sie Pull Requests erstellen und überprüfen.
|
||||
- [Architekturübersicht](../architecture/overview.md): Überblick über die Architektur des Frameworks.
|
||||
Reference in New Issue
Block a user