# Dokumentation erweitern

Letzte Aktualisierung: 2026-02-21

## Ziel

Diese Seite beschreibt den Standardprozess, um die Projektdokumentation sauber, konsistent und dauerhaft wartbar zu erweitern.

## Single Source of Truth

- Für Doku-Navigation und Doku-Suche ist **`/docs/index.md`** die einzige Quelle.
- Nur Dateien, die dort eingetragen sind, erscheinen in:
  - `/admin/docs/...`
  - globaler Suche (Kategorie `Documentation`)
  - Vollsuche `/search`
- Der sichtbare Name im Docs-Aside und in der Suche kommt aus dem **H1-Titel** der Datei.

## Standardablauf für neue Doku-Dateien

1. Neue Datei unter `docs/*.md` anlegen (Slug nur `a-z`, `0-9`, `-`).
2. Erste Zeile als H1 setzen (`# Titel`).
3. Direkt darunter Datum setzen:
   - `Letzte Aktualisierung: YYYY-MM-DD`
4. Datei in `docs/index.md` unter passender Kategorie eintragen:
   - Format: ``/docs/<slug>.md``
5. Kurzbeschreibung in `docs/index.md` ergänzen (1 Zeile, klarer Nutzen).
6. Relevante Querverweise in bestehenden Docs ergänzen.

## Struktur- und Stilregeln

- Pro Datei genau ein H1.
- H1 ist der kanonische Anzeigename (Navigation + Suche).
- Abschnittsstruktur über H2/H3 (nicht direkt mit H4 starten).
- Ein Abschnitt = eine klare Aussage.
- Befehle in Codeblöcken mit realen, lauffähigen Beispielen.
- Dateipfade immer als klickbare Code-Referenz (`/path/to/file`).
- Keine veralteten Relikte stehen lassen ("Legacy", alte Namen, alte Routen).

## Wichtig für die Suche

- Doku-Suche indexiert `docs/*.md` live.
- Treffer entstehen aus:
  - Dokumenttitel
  - Abschnittsüberschriften (H1/H2/H3)
  - Abschnittstext
- Links springen auf `admin/docs/{slug}#anchor`.
- Aussagekräftige H2/H3-Überschriften verbessern Suchtreffer deutlich.

## Qualitätscheck vor Merge

1. Ist die Datei in `docs/index.md` eingetragen?
2. Ist `Letzte Aktualisierung` vorhanden und korrekt?
3. Stimmen alle genannten Pfade/Routen/Permissions mit dem Code?
4. Gibt es mindestens einen konkreten, praxisnahen Beispielaufruf?
5. Sind neue Begriffe konsistent zu bestehender Terminologie?

## Häufige Fehler

- Datei erstellt, aber nicht in `docs/index.md` registriert.
- Überschrift/Slug später umbenannt, alte Links nicht angepasst.
- Allgemeine Aussagen ohne konkrete Beispiele.
- API-/Permission-Änderung im Code, aber Doku nicht nachgezogen.