63 lines
2.3 KiB
Markdown
63 lines
2.3 KiB
Markdown
|
# 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.
|