forked from fa/breadcrumb-the-shire
fs
545bcc789b
Most German docs were written with `ue`/`ae`/`oe`/`ss` ASCII fallbacks (`fuer`, `aenderung`, `koennen`, `gemaess`) — relic from older toolchain constraints. Replaced 237 occurrences across 38 .md files with proper umlauts and ß so the docs read naturally. Substitutions are constrained to plain prose: fenced code blocks (```...```), inline code spans (`...`), markdown link targets `[..](..)`, and HTML comments are preserved verbatim. Path references like `docs/howto-erste-aenderung.md` keep their original (umlaut-replaced) filenames — only the surrounding prose is normalised. Tool: bin/fix-md-umlauts.py (idempotent — no-op on already-clean files). Re-runnable if ASCII fallbacks creep back in via copy-paste. Doc-link-check + doc-drift-check stay green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
62 lines
2.1 KiB
Markdown
62 lines
2.1 KiB
Markdown
# 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.
|