Kapitel für eine Kurs-Website schreiben, die das Warum vor der Formel erklären

## Festlegen, wo Kursseiten und Übersetzungen liegen Das Projekt ist eine statische Dokumentationswebsite, die aus Quelldateien im Repository erzeugt wird. Halte den Verzeichnisbaum vorhersagbar, damit Mitwirkende erraten können, wo etwas liegt: - `docs/` — die Kursinhalte, aus denen die veröffentlichten Seiten entstehen. - Das Verzeichnis für die Website-Konfiguration innerhalb des Inhaltsbaums — Konfiguration und Theme-Anpassungen für den statischen Website-Generator. - `docs/public/` — statische Assets, die unverändert in die fertige Website übernommen werden. - Ein Verzeichnis je zusätzlicher Sprache innerhalb des Inhaltsbaums — Übersetzungsbäume, die den Aufbau der Hauptsprache spiegeln. Rumpfseiten sind in einem Übersetzungsbaum als Platzhalter zulässig. - `code/` — lauffähige Experimente, Kapitel für Kapitel auf den Fließtext abgestimmt. - `scripts/` — Wartungsskripte des Repositorys, etwa zur Erzeugung der Sitemap, zur Überprüfung und zur Asset-Optimierung. - Das Verzeichnis des CI-Workflows — die Pipeline, die die Website baut und ausliefert. Neues Material kommt unter das Inhaltsverzeichnis. Einträge in Navigation und Seitenleiste werden in der Konfigurationsdatei der Website deklariert und niemals allein aus der Ablage der Dateien abgeleitet. ## Die Website mit den Befehlen des Projekts lokal ansehen und prüfen Arbeite über die Skript-Einstiegspunkte des Projekts selbst, statt die darunterliegenden Werkzeuge direkt aufzurufen, damit alle dieselbe Pipeline durchlaufen. Eine Dokumentationswebsite dieser Bauart stellt davon einen kleinen, festen Satz bereit: - `npm install` — Abhängigkeiten installieren. - `npm run dev` — Entwicklungsserver mit Asset-Optimierung. - `npm run dev:fast` — Entwicklungsserver ohne Asset-Optimierung, für einen deutlich schnelleren Start. - `npm run build` — die veröffentlichungsfähige Ausgabe erzeugen. - `npm run preview` — die gebaute Ausgabe genau so ausliefern, wie sie veröffentlicht wird. - `npm run verify` — Konsistenzprüfungen über das gesamte Repository. - `npm run assets:optimize` — Bilder komprimieren und umwandeln. Nutze beim Bearbeiten von Fließtext die schnelle Entwicklungsvariante, denn dort ändert die Bildoptimierung nichts an dem, was du dir ansiehst. Nutze `build` gefolgt von `preview`, wenn du die Ausgabe genau so sehen musst, wie sie veröffentlicht wird. `verify` ist das Tor, das im nächsten Teil beschrieben wird, und `assets:optimize` wird nach dem Hinzufügen von Bildern ausgeführt, damit große Originale niemals auf die veröffentlichte Website gelangen. ## Das Menü jeder Sprache anpassen und vor dem Veröffentlichen prüfen - Halte jede Änderung auf die anstehende Aufgabe begrenzt. Schreibe keine unbeteiligten Dokumente oder Konfigurationen um, nur weil du gerade daran vorbeikommst. - Füge neues Kursmaterial lieber unter dem Inhaltsverzeichnis hinzu, statt bereits vorhandenes Material umzubauen. - Trage neue Seiten beim Hinzufügen in die Konfiguration von Navigation und Seitenleiste ein. - Wird eine Seite hinzugefügt, verschoben oder umbenannt, aktualisiere die Seitenleiste jedes Sprachbaums, der sie spiegelt, und nicht nur die der Hauptsprache. Ein zurückgelassener Übersetzungsbaum erzeugt einen toten Eintrag oder eine fehlende Seite. - Führe den Überprüfungsbefehl vor dem Push immer dann aus, wenn Konfiguration, Theme oder Build-Skripte angefasst wurden. Ein Push veröffentlicht die Website; ein ungeprüfter Build macht sie damit öffentlich kaputt. ## Formel-Diagramme in LaTeX schreiben und in SVG umwandeln Abbildungen im akademischen Stil mit echtem mathematischem Satz werden als Quelltext verfasst und nicht von Hand gezeichnet: 1. Schreibe das Diagramm als eigenständiges Dokument in einer Sprache für Vektordiagramme — zum Beispiel als eigenständiges LaTeX-Dokument mit einem Paket im TikZ-Stil. Übernimm den Stil einer bereits im Repository vorhandenen Abbildung, statt einen neuen zu erfinden. 2. Übersetze den Quelltext mit einer LaTeX-Engine, die die verwendeten Schriften unterstützt, und wandle das entstandene PDF anschließend mit einem PDF-zu-SVG-Konverter in SVG um. Beide Schritte sind Kommandozeilenwerkzeuge, sodass jede Abbildung jederzeit aus ihrem Quelltext neu erzeugt werden kann. 3. Bewahre sowohl die Quelldatei als auch das erzeugte SVG im selben `images/`-Verzeichnis auf, direkt neben dem Kapitel, das sie verwendet, damit die Abbildung reproduzierbar bleibt. 4. Verweise von der Markdown-Seite aus über einen relativen Pfad auf das erzeugte SVG. Halte über alle Abbildungen hinweg einen einheitlichen visuellen Stil: Kästen mit abgerundeten Ecken, sehr heller Füllung und dunkelgrauer Kontur, eine einzige Form der Pfeilspitze, eine Textschrift passend zum Fließtext und Inline-Mathematik-Begrenzer für Symbole. ## Im geduldigen Vortragston schreiben, nicht im Plauderton - Schreibe Kapitel als Tutorial- und Vorlesungsmaterial, nicht als knappe Nachschlagenotizen. - Halte die Stimme einer geführten Vorlesung: dialogisch, geduldig und von Problemen getrieben. Wendungen, die den Lesenden den nächsten Schritt reichen — „Beginnen wir mit der Anschauung", „Betrachten wir es aus einem anderen Blickwinkel", „Was dieser Schritt bedeutet, ist …", „Das eigentliche Problem ist …" —, sind willkommen, während der Ton ernsthaft und präzise bleibt. - Verfalle nicht in plaudernde, assistenzhafte oder salopp-internettypische Formulierungen. Die Zielsprachebene ist die eines ausgefeilten Lehrbuchkapitels. - Takte Absätze so, dass sie vorgelesen oder allein durchgearbeitet werden können. Lässt sich ein Absatz nicht in Lesegeschwindigkeit verfolgen, teile ihn auf. ## Die ganze Begründung erklären und keine leeren Füllsätze schreiben Tiefe und Sparsamkeit gehören zusammen: Erkläre die gesamte Gedankenkette und verschwende kein Wort auf irgendetwas außerhalb dieser Kette. - Erkläre schrittweise — zuerst die Anschauung, dann die formale Definition, dann Code oder Praxis. - Gib den Hintergrund an und den Grund, warum ein Schritt nötig ist. Presse ein Kapitel nicht zu einer nackten Liste von Ergebnissen zusammen. - Streiche hinführendes Füllmaterial. Ein Satz, der eine Erklärung ankündigt, statt sie zu geben („ein Beispiel macht das anschaulicher"), wird gelöscht, und das Beispiel oder die Formel wird direkt gezeigt. - Sage jede Sache einmal. Wiederhole denselben Punkt nicht mit anderen Worten. - Ersetze vage Abschwächungen durch präzise Kausalaussagen. Metaphorische Ersatzformeln („das entspricht ungefähr …") und absichernde Bindewörter gehören ausschließlich in einen ersten Entwurf. - Vermeide schlagwortartige Zusammenfassungen, die einen Mechanismus zu einer griffigen Wendung zusammenpressen. Nenne stattdessen den konkreten Mechanismus. - Vermeide maschinell klingende Aufzählungen gleichförmiger Fehler („die Abfrage war zu breit, kein Preisvergleich, falscher Lagerbestand, falscher Parameter"). Beschreibe den Ablauf und zeige, wie sich ein einziger früher Fehlzustand in die späteren Handlungen fortpflanzt. - Vermeide das Kontrastmuster „nicht A, sondern B"; es wirkt indirekt. Stelle die positive Aussage auf und erkläre dann, warum sie gilt. ## Gedanken so ordnen, dass jeder neue Schritt seinen Grund mitbringt - Folge der kausalen Linie. Umkreise denselben Punkt nicht, indem du ihn zusammenfasst, neu formulierst und ihm dann etwas gegenüberstellst. Schreibe in der Reihenfolge, in der sich der Gedanke tatsächlich verändert: Eine neue Fähigkeit oder Rahmenbedingung tritt auf, sie verändert das Trainings- oder Problemobjekt, und dadurch wird eine neue Formulierung möglich oder unvermeidlich. - Wähle beim Einführen eines neuen Begriffs bevorzugt die Form „nun, da X existiert, tut das System Y, also wird Z möglich (oder notwendig)". - Eröffne einen Abschnitt mit dem Anschluss an das, was die Lesenden bereits kennen, und benenne dann das neue Problem, das dieser Abschnitt löst. - Verweise nicht auf frühere Kapitel zurück, es sei denn, der Rückverweis wird für den unmittelbar folgenden Satz gebraucht. - Gib jedem gedanklichen Schritt einen Übergang. Springe niemals direkt von einer Definition zu einer Formel, einem Fachwort, einem Algorithmus oder einer Schlussfolgerung; sage vor der Einführung des nächsten Gedankens, warum er gebraucht wird. - Schreibe keine enzyklopädischen Seiten, die nur Definitionen aufzählen. Eine Definition kommt nach ihrer Motivation und wird von einer Deutung gefolgt. - Lass Absätze von der Frage zur Antwort laufen. Ein gut gebauter Abschnitt folgt meist diesem Rhythmus: vertrautes Beispiel → Spannung oder Verwirrung → formales Werkzeug → durchgerechnetes Beispiel → Kernaussage. ## Vor der Formel ein vertrautes Beispiel zeigen und jedes Symbol erklären - Nenne vor der Einführung einer Formel oder eines Algorithmus das Problem, das damit gelöst wird; erst danach zeige die Notation. - Halte eine Formel neben ihrer Bedeutung: Erkläre jedes wichtige Symbol und formuliere anschließend die ganze Formel in einfacher Sprache noch einmal. - Greife vor einer Abstraktion zu einer konkreten Szene. Kleine vertraute Anordnungen — eine Regelungsaufgabe zum Balancieren eines Stabs, ein mehrarmiger Bandit, Textgenerierung, eine Spielaufgabe, eine alltägliche Entscheidung — sollen einen Begriff notwendig erscheinen lassen, bevor er benannt wird. - Baue kleine Herleitungen ein, statt Ergebnisse nur zu behaupten, und halte den Fließtext durchgehend an den Lernenden ausgerichtet. - Schreibe Fachbegriffe in der Hauptsprache des Fließtexts, sobald eine etablierte Entsprechung existiert, statt das entlehnte englische Wort unübersetzt stehen zu lassen. Behalte einen englischen Begriff nur dann bei, wenn es ein gängiges Akronym ist oder wenn der Kapiteltitel ihn verlangt, und erkläre ihn bei der ersten Verwendung. - Verwende im gesamten Kurs pro Begriff ein festes Wort. Ein Synonym, das von Kapitel zu Kapitel abweicht, liest sich für Lernende als zweiter Begriff. ## Kurze Abschnitte mit Überschriften nutzen und Commits mit feat: usw. beginnen - Verwende kurze Abschnitte mit ausdrücklichen Überschriften statt langer ungegliederter Textstrecken. - Verwende Fettschrift sparsam, um einen begrifflichen Wendepunkt zu markieren — niemals als Schmuck. - Verwende kebab-case für Pfade unter dem Inhaltsverzeichnis. - Bevorzuge verzeichnisbasierte Routen mit einer `index.md` darin, damit ein Thema zu mehreren Seiten wachsen kann, ohne seine URL zu ändern. - Verwende für jede Änderung Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:` und so weiter.