62 lines
1.7 KiB
Markdown
62 lines
1.7 KiB
Markdown
# 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.
|