breakpilot-pwa/docs-src/development/documentation.md

# Dokumentations-Regeln

## Automatische Dokumentations-Aktualisierung

**WICHTIG:** Bei JEDER Code-Aenderung muss die entsprechende Dokumentation aktualisiert werden!

## Wann Dokumentation aktualisieren?

### API-Aenderungen

Wenn du einen Endpoint aenderst, hinzufuegst oder entfernst:

- Aktualisiere die [Backend API Dokumentation](../api/backend-api.md)
- Aktualisiere Service-spezifische API-Docs

### Neue Funktionen/Klassen

Wenn du neue Funktionen, Klassen oder Module erstellst:

- Aktualisiere die entsprechende Service-Dokumentation
- Fuege Code-Beispiele hinzu

### Architektur-Aenderungen

Wenn du die Systemarchitektur aenderst:

- Aktualisiere die [System-Architektur](../architecture/system-architecture.md)
- Aktualisiere Datenmodell-Dokumentation bei DB-Aenderungen

### Neue Konfigurationsoptionen

Wenn du neue Umgebungsvariablen oder Konfigurationen hinzufuegst:

- Aktualisiere die entsprechende README
- Fuege zur [Umgebungs-Setup](../getting-started/environment-setup.md) hinzu

## Dokumentations-Format

### API-Endpoints dokumentieren

```markdown
### METHOD /path/to/endpoint

Kurze Beschreibung.

**Request Body:**
```json
{
  "field": "value"
}
```

**Response (200):**
```json
{
  "result": "value"
}
```

**Errors:**
- `400`: Beschreibung
- `401`: Beschreibung
```

### Funktionen dokumentieren

```markdown
### FunctionName (file.go:123)

```go
func FunctionName(param Type) ReturnType
```

**Beschreibung:** Was macht die Funktion?

**Parameter:**
- `param`: Beschreibung

**Rueckgabe:** Beschreibung
```

## Checkliste nach Code-Aenderungen

Vor dem Abschluss einer Aufgabe pruefen:

- [ ] Wurden neue API-Endpoints hinzugefuegt? → API-Docs aktualisieren
- [ ] Wurden Datenmodelle geaendert? → Architektur-Docs aktualisieren
- [ ] Wurden neue Konfigurationen hinzugefuegt? → README aktualisieren
- [ ] Wurden neue Abhaengigkeiten hinzugefuegt? → requirements.txt/go.mod UND Docs
- [ ] Wurde die Architektur geaendert? → architecture/ aktualisieren

## Beispiel: Vollstaendige Dokumentation einer neuen Funktion

Wenn du z.B. `GetUserStats()` im Go Service hinzufuegst:

1. **Code schreiben** in `internal/services/stats_service.go`
2. **API-Doc aktualisieren** in der API-Dokumentation
3. **Service-Doc aktualisieren** in der Service-README
4. **Test schreiben** (siehe [Testing](./testing.md))

## Dokumentations-Struktur

Die zentrale Dokumentation befindet sich unter `docs-src/`:

```
docs-src/
├── index.md                    # Startseite
├── getting-started/            # Erste Schritte
│   ├── environment-setup.md
│   └── mac-mini-setup.md
├── architecture/               # Architektur-Dokumentation
│   ├── system-architecture.md
│   ├── auth-system.md
│   └── ...
├── api/                        # API-Dokumentation
│   └── backend-api.md
├── services/                   # Service-Dokumentation
│   ├── klausur-service/
│   ├── agent-core/
│   └── ...
├── development/                # Entwickler-Guides
│   ├── testing.md
│   └── documentation.md
└── guides/                     # Weitere Anleitungen
```

## MkDocs Konventionen

Diese Dokumentation wird mit MkDocs + Material Theme generiert:

- **Admonitions** fuer Hinweise:
  ```markdown
  !!! note "Hinweis"
      Wichtige Information hier.

  !!! warning "Warnung"
      Vorsicht bei dieser Aktion.
  ```

- **Code-Tabs** fuer mehrere Sprachen:
  ```markdown
  === "Python"
      ```python
      print("Hello")
      ```

  === "Go"
      ```go
      fmt.Println("Hello")
      ```
  ```

- **Mermaid-Diagramme** fuer Visualisierungen:
  ```markdown
  ```mermaid
  graph LR
      A --> B --> C
  ```
  ```