fa/breadcrumb-the-shire
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
99db252f60a05261049c4e92ac93d8f0a74c0968
breadcrumb-the-shire/docs/dokumentation-erweitern.md
fs 25370a1a55 add composer-unused, comprehensive docs, and project restructure 
- Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks
- Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists
- Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services
- Add Microsoft OIDC SSO, API token management, and user lifecycle features
- Add swagger-ui vendor integration and OpenAPI spec
- Add production Docker setup and bin/ scripts
- Update composer dependencies, config, templates, and frontend assets throughout

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-22 15:27:35 +01:00

2.3 KiB
Raw Blame History

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.
Reference in New Issue View Git Blame Copy Permalink