Zum Inhalt springen
Esc
↑↓navigieren↵öffnen⌘Jvorschau
Auf dieser Seite

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; elw taucht 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 :::note brauchen 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 Beispiel anwender/02-einsaetze/bilder/einsatz-anlegen-formular.png. Eingebunden relativ: ![Formular Einsatzdaten](./bilder/einsatz-anlegen-formular.png). 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.