# Dokumentation erweitern

Letzte Aktualisierung: 2026-02-24

## 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`)

Hauptbereiche in genau dieser Reihenfolge:

1. Lernpfad (chronologisch)
2. Konzepte (Explanation)
3. Aufgabenanleitungen (How-to)
4. Referenz (Reference)
5. Betrieb (Operations)
6. Mitwirken (Contributor Guide)

## 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/*.md` anlegen (`a-z`, `0-9`, `-`).
2. Seite im passenden Bereich 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/architektur.md` und `/docs/lib-standards.md`.
5. Mindestens ein konkretes Beispiel ist enthalten.
6. Begriffe sind konsistent mit `/docs/02-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.