breadcrumb-the-shire/docs/dokumentation-erweitern.md

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.