Das Handbuch pflegen
Pflicht zum Mitschreiben, Seiten schreiben, Screenshots, lokal ansehen und bauen.
Das Handbuch liegt in handbuch/ und wird mit Blume gebaut.
Lokal ansehen
cd handbuch
npm install
npm run dev
Vor dem Commit:
npm run build # bricht bei kaputtem Frontmatter oder MDX ab
npx blume validate # prüft alle internen Links
Im Dev-Stack läuft das gebaute Handbuch unter https://handbuch.localhost.
Abhängigkeiten
Renovate hält Blume und das nginx-Image aktuell. Updates fürs Handbuch tragen das Label
handbuch; Minor- und Patch-Updates kommen gebündelt in einem Merge Request „Handbuch
dependencies“, Sicherheitsupdates in „Handbuch Vulnerability Alerts“. test:handbuch baut jedes
Update streng. Das npm-Override für path-to-regexp in package.json schließt eine Lücke im
ungenutzten Vercel-Adapter von Blume; es kann weg, sobald Blume es nicht mehr braucht.
Aufbau
handbuch/
blume.config.ts Titel, Tabs, Sprache
inhalt/
index.mdx Startseite
anwender/ Tab „Anwender“
administration/ Tab „Administration“
entwicklung/ Tab „Entwicklung“
Jeder Ordner ist eine Gruppe in der Seitenleiste. Nummernpräfixe wie 02- bestimmen die
Reihenfolge der Gruppen und fallen in der URL weg: anwender/02-einsaetze/einsatz-anlegen.mdx
wird zu /anwender/einsaetze/einsatz-anlegen. Die Reihenfolge der Seiten in einer Gruppe steht
in deren meta.ts (pages). Eine neue Seite gehört dort eingetragen. Einzelne Themen auf
oberster Ebene liegen als Ordner mit index.mdx, sonst rutschen sie in der Seitenleiste über
alle Gruppen.
Schreibregeln
- Das Produkt heißt im Text immer Lagewerk;
elwtaucht nur in technischen Bezeichnern auf (Pfade, Hostnamen, Container). - Anrede „Sie“, sachlich und knapp. Begriffe, Knöpfe und Menüs exakt wie in der Oberfläche, in Fettschrift.
- Nur beschreiben, was umgesetzt ist. Spez und Code können abweichen, dann gilt der Code.
- Im Anwender-Teil keine API-Pfade, Tabellennamen oder Permission-Keys; Rechte heißen so wie in der Rollenverwaltung.
- Fachliche Regeln (was wann nicht geht, was automatisch passiert) gehören hinein, sie sind das Wertvollste am Handbuch.
- Frontmatter-Werte mit „: “ in Anführungszeichen setzen.
- Komponenten wie
<Steps>,<Card>und Hinweise mit:::notebrauchen keinen Import. Übersicht: Blume-Komponenten.
Screenshots
Screenshots machen Abläufe schneller verständlich. Sie veralten aber mit jeder Änderung an der Oberfläche und werden deshalb im selben Merge Request erneuert.
- Ablage: neben der Seite in einem Ordner
bilder/, zum Beispielanwender/02-einsaetze/bilder/einsatz-anlegen-formular.png. Eingebunden relativ:. Blume optimiert die Bilder beim Bauen. - Aufnahme: gegen den Dev-Stack (https://elw.localhost) mit Testdaten, nie mit echten Patientendaten. Helles Farbschema, Fensterbreite 1440 px, nur der relevante Ausschnitt. Playwright eignet sich für wiederholbare Aufnahmen.
- Alternativtext beschreibt, was zu sehen ist.
- Ein Screenshot ersetzt keine Beschreibung: Regeln und Schritte stehen weiter im Text.
Diagramme
Abläufe und Strukturen als Mermaid-Codeblock direkt in der Seite. Frei gelayoutete Diagramme als
.drawio.svg in bilder/: Die Datei ist ein normales Bild für Blume und lässt sich zugleich in
draw.io öffnen und bearbeiten (Desktop, Web oder VS-Code-Erweiterung). Eine .excalidraw-Fassung
daneben ist erlaubt, eingebunden wird das SVG. Nach dem Bearbeiten als .drawio.svg speichern,
nicht als reines SVG, sonst gehen die Diagrammdaten verloren. Blume meldet dazu beim Bauen
BLUME_SVG_UNOPTIMIZED: Die eingebetteten Diagrammdaten verdecken die Bildgröße, das Bild wird
unverändert ausgeliefert. Das ist gewollt und harmlos.
Die Diagramme auf Entwicklung › Architektur entstehen per Skript aus einem gemeinsamen Modell
(scripts/diagramme/, Aufruf python3 scripts/diagramme/erzeugen.py). Für sie ist das Skript die
Quelle: Änderungen dort eintragen und neu erzeugen, nicht in draw.io oder Excalidraw. Angezeigt
werden Excalidraw-Exporte in Hell und Dunkel (<name>.excalidraw.svg, <name>.excalidraw.dark.svg);
sie werden nach jedem Lauf von Hand aus der neuen .excalidraw exportiert (Anleitung in
scripts/diagramme/README.md). Die Seite bindet beide per Import ein und schaltet mit den Klassen
dark:hidden und hidden dark:inline-flex um.