Zum Hauptinhalt springen

Doku-Pflege

Diese Seite erklärt wie diese Doku selbst gepflegt wird — Style-Guide, Welle-Pattern, Drift-Check, Templates. Für jeden, der die Doku weiterentwickelt.

Doku-Architektur​

docs/
├── anwender/         # Persona-orientierte Tutorials (~80)
│   ├── techniker/
│   ├── innendienst/
│   ├── ...
│   └── admin/
├── cheat-sheets/     # 13 Persona-1-Seiter
├── grundlagen/       # 11 Querschnitt-Themen (FAQ, Glossar, KI-Chat)
├── konzepte/         # 21 Architektur-/Domänen-Konzepte
├── api/              # 7 Entwickler-API-Seiten
├── _template/        # Vorlagen für neue Seiten
└── <module-routes>/  # 177 Modul-Doku-Seiten (technische Referenz)

src/
├── pages/sitemap.mdx # Master-Index
├── pages/roadmap.mdx # Was ist da, was kommt
└── components/...    # Custom-Komponenten

_internal/
├── HANDOVER.md       # Status pro Session
├── workflow.md       # Spielregeln
├── codebase-inventory.md # Architektur-Übersicht
└── drift-report-*.md # Drift-Audit pro Stand

Style-Guide​

Sprache​

  • Deutsch im Body, Sie-Form
  • Echte Umlaute (ä/ö/ü/ß), nicht ae/oe/ue/ss
  • Keine Marketing-Sprache („revolutionär", „vollumfänglich")
  • Keine Emojis
  • Unicode-Pfeile/Bullets erlaubt

Tutorial-Stil (Anwender)​

  1. Wann mache ich das? — Trigger-Situationen
  2. <Voraussetzung> — Vorbereitung
  3. So gehen Sie vor mit <TutorialSchritt nummer={N} titel="..."> Blöcken
  4. Pro Schritt: Was Sie machen + Wie + Warum + ggf. Stolperstein
  5. Weg 2 — KI-Chat Section (wo sinnvoll)
  6. Was tue ich, wenn etwas schiefgeht? mit <Stolperstein>-Boxen
  7. Tipps aus der Praxis
  8. Verwandte Tutorials
  9. <AdminDetails> klappbarer Block für technische Tiefe

Modul-Doku-Stil (technische Referenz)​

  • Pflicht-Sektionen in fester Reihenfolge — siehe docs/_template/modul-seite.md
  • Felder-Tabelle Pflicht-Spalten: Feldname / Pflicht / Datentyp / Wirkung / Voraussetzung
  • CASL mit Subjects + Keycloak-Rolle

Konzept-Stil​

  • Mermaid-Diagramme wo sinnvoll
  • Pattern-Erklärung mit Code-Beispielen
  • Edge-Cases explizit aufzählen
  • Anti-Patterns als „was NICHT machen"

Welle-Pattern für neue Doku​

Pro Welle:

  • 4-9 Doku-Seiten, fokussiertes Thema (z.B. „Buchhaltung-SB-Cluster")
  • Cross-Refs zu verwandten Tutorials in Voraussetzung + Verwandte
  • Build muss grün sein
  • Commit-Message: „Welle X: <Thema>" + Co-Authored-By

Custom-Komponenten​

In src/theme/MDXComponents.tsx registriert (ohne Import nutzbar):

KomponenteWofür
<TutorialSchritt nummer={N} titel="">Schritt-Block mit Gradient-Nummer
<Voraussetzung>Vorbereitungs-Liste
<Stolperstein titel?>Warn-Callout für Edge Cases
<KIHinweis titel?>Info-Callout
<AdminDetails titel?>klappbarer Block
<PersonaGrid spalten={2}>Persona-Tile-Container
<PersonaTile href titel rolle geraet aufgaben={[]}>Persona-Karte
<Screenshot status="todo" beschreibung="">Placeholder für Bilder
<ModulStatus>Status-Badge

Frontmatter-Pflichtfelder​

Pro Modul-Doku-Seite:

---
title: ...                  # H1 + Browser-Tab
sidebar_position: 1         # Reihenfolge
slug: /...                  # URL
description: ...            # Meta-Description
status: live | draft        # Status
endpoint: /...              # FE-Route (für Drift-Check)
api_endpoints: [...]        # BE-Routes
casl: [Subject:action]      # Doku-Format Subject:action
casl_fe: [FE_Subject:view]
modul: ...
tags: [...]
letzte_aktualisierung: YYYY-MM-DD
verantwortlich: Team
---

Anwender-Tutorials brauchen endpoint/api_endpoints/casl nicht.

Drift-Check​

npm run drift-check          # Markdown-Bericht
npm run drift-check:json     # für Skript-Verarbeitung
npm run drift-check:strict   # exit 1 bei Drift (CI-Modus)

Drift-Skript prüft pro Modul-Doku:

  • Existiert die Route im FE-Code?
  • Stimmen die CASL-Subjects mit dem Code überein?
  • Critical drift: Code hat Subjects, die in Doku fehlen

Bei Critical-Drift: node scripts/drift-fix.mjs (auto-ergänzt fehlende Subjects).

Native Screenshots​

Pipeline für Anwender-Tutorial-Screenshots:

# 1. Chrome-MCP-Tab auf demo.speamcore.com offen
# 2. Helper-Skript (siehe /tmp/snap.sh):
#    - Window auf 1280x900 setzen
#    - Tab in Front bringen
#    - macOS screencapture -R "100,230,1280,755"
# 3. PNG landet unter static/img/screenshots/anwender/<tutorial>/

Wichtig: TAB_INDEX prüfen (nicht immer 1), caffeinate -u -t 3 gegen Display-Sleep.

Pull-Request-Workflow​

Aktuell direkter Commit auf main. Für externe Beiträge:

  1. Fork
  2. Feature-Branch
  3. Welle bauen (siehe Pattern oben)
  4. PR mit Welle-Message
  5. Doku-Team reviewt + merged

Externe Repos (read-only)​

  • FE: Projektordner/Speamcore/speamcore.com
  • BE: Projektordner/Speamcore/api.speamcore.com

Niemals committen / pushen / branchen in den FE/BE-Repos. Vor jeder Doku-Session beide auf master + git pull.

Was zu vermeiden ist​

  • ❌ Routen erfinden — Liste der nicht-existenten in _internal/HANDOVER.md
  • ❌ Felder/Endpoints/CASL-Subjects erfinden — <!-- TODO: mit Marc abstimmen -->
  • ❌ Branchwechsel oder Pushes in FE/BE-Repos
  • ❌ npm install ohne Grund — Dependencies eingefroren
  • ❌ Massen-Edits ohne Build-Check zwischen drin
  • ❌ Screenshots selbst generieren (canvas) — nur native via Chrome MCP

Bei Unsicherheit​

Frag Marc nach. Lieber nachfragen als undokumentierte Funktionen ausliefern.

Verwandte Doku (intern, nur im Repo)​

Die folgenden Dateien liegen unter _internal/ im Doku-Repo und werden nicht auf der Public-Site gerendert. Direkt im Git-Repo nachschlagen:

  • _internal/workflow.md — Spielregeln (intern)
  • _internal/codebase-inventory.md — Architektur (intern)
  • _internal/HANDOVER.md — Stand pro Session (intern)