# Dokumentation erweitern

Letzte Aktualisierung: 2026-03-06

## Ziel

Neue Seiten schnell, konsistent und langfristig wartbar ergänzen.

## Informationsarchitektur (verbindlich)

`/docs/index.md` ist die einzige Navigationsquelle für:

- Admin-Doku (`/admin/docs/...`)
- Docs-Suche
- Vollsuche (`/search`)

Die Dokumentation folgt dem Diataxis-Modell mit genau vier Quadranten in dieser Reihenfolge:

1. **Tutorials** — Lernorientierte Schritt-für-Schritt-Anleitungen
2. **How-to Guides** — Aufgabenorientierte Anleitungen für konkrete Ziele
3. **Explanation** — Verstaendnisorientierte Hintergrunderklaerungen
4. **Reference** — Informationsorientierte Fakten und Nachschlagewerke

Dateinamenformat: `<quadrant-prefix>-<slug>.md`, wobei Prefix nur `tutorial-`, `howto-`, `explanation-`, `reference-` ist.

## Format pro Seite (kurz und klar)

Jede neue Seite soll kompakt bleiben:

- genau ein H1
- `Letzte Aktualisierung: YYYY-MM-DD`
- `## Ziel` (1-2 Sätze)
- maximal 3-6 H2-Abschnitte
- kurze Listen statt Fließtextblöcke
- konkrete Befehle oder Pfade

Richtwert: zuerst kurz, Details als Verweis auf Referenzseiten.

## Standardablauf

1. Datei in `docs/<prefix>-<slug>.md` anlegen (Prefix: `tutorial-`, `howto-`, `explanation-`, `reference-`).
2. Seite im passenden Diataxis-Quadranten in `docs/index.md` eintragen.
3. Aussagekräftige H2/H3-Überschriften setzen (für Suche).
4. Relevante Querverweise ergänzen.
5. Datum aktualisieren.

## Qualitätscheck vor Merge

1. Seite ist in `docs/index.md` eingetragen.
2. Struktur ist kurz, klar, ohne Redundanz.
3. Pfade, Routen, Permissions stimmen mit dem Code.
4. Instanziierungsregeln sind konsistent mit `/docs/explanation-architektur.md` und `/docs/reference-core-standards.md`.
5. Mindestens ein konkretes Beispiel ist enthalten.
6. Begriffe sind konsistent mit `/docs/reference-domain-glossar.md`.

## Häufige Fehler

- Seite existiert, ist aber nicht im Index registriert.
- Lernpfad wird mit Referenztext überladen.
- Lange Detailtexte ohne klare Handlungsschritte.
- API-/Permission-Änderung im Code ohne Doku-Update.
