IbrahimSobh/content-explainer-slide

Content Explainer Slide (Inhaltserklärfolie)

Erstellt ein einzelnes Bild, das die Geschichte einer technischen Arbeit erzählt: Was wurde bemerkt, was war falsch, was wurde getan und warum jeder Schritt funktioniert, woher jede Zahl stammt und was erreicht und gelernt wurde.

Die Messlatte ist 100% klar und intuitiv für einen Junioringenieur, nicht 100% detailliert. Diese Messlatte stammt aus echten Überprüfungsrunden: Jedes Mal, wenn ein Begriff undefiniert war, eine Zahl keine sichtbare Herkunft hatte, der Grund eines Schritts in einer Fußnote versteckt war oder eine Karte einen leeren Bereich hatte, kam der Leser zurück mit "Was ist das?", "Wo kommt die 30 her?", "Warum funktioniert das?" – und die Folie benötigte eine weitere Runde. Alles, was unten steht, existiert, um diese Fragen auf der Folie zu beantworten, bevor der Leser sie stellen muss.

Ein ausgearbeitetes Beispiel eines fertigen Folienplans (ein "Neuron-Chirurgie"-Experiment mit neuronalen Netzen) befindet sich in references/worked-example.md. Lies es einmal durch, bevor du deine erste Folie planst; es zeigt, wie jede Karte aussieht, wenn die Regeln angewendet werden.

Schritt 0 – Frage nach dem Ausgabeformat, dann erstelle ein Faktenblatt

Frage nach dem Format (einmal, vor dem Zeichnen)

Frage den Benutzer, welches Ausgabeformat er wünscht, es sei denn, er hat es bereits genannt:

• PNG via matplotlib (Python) – am besten, wenn die Eingabe Daten, Modelle, Logs oder Ergebnisdateien enthält, weil ein Skript jede Zahl auf der Folie direkt aus diesen Dateien berechnen kann (keine handgetippten Zahlen). Exportiert auch eine JPG-Kopie.
• HTML/SVG-Seite gerendert zu PNG – am besten, wenn die Eingabe nur Text ist (ein Paper, ein Dokument, Notizen), oder wenn Typografie und Layout-Präzision wichtiger sind als die Berechnung von Zahlen. Wird mit Headless Chrome/Edge zu PNG gerendert.
• Beides – gleicher Folienplan, zwei Renderings.

Gib deine Empfehlung mit Begründung ab (Dateneingabe → matplotlib; Texteingabe → HTML). Wenn der Benutzer nicht gefragt werden kann (automatisierter Durchlauf), wähle nach dieser Regel und sage, was du gewählt hast und warum.

Erstelle das Faktenblatt

Bevor du etwas entwirfst, liste jede Tatsache auf, die die Folie verwenden könnte. Notiere für jede Tatsache:

Tatsache	Wert	Gemessen an (welchen Daten / welchem Abschnitt)	Quelle (Datei + Skript, oder Papierseite/Tabelle)

Dann:

• Überprüfe Fakten gegenseitig und gegen jeden Entwurfstext (einen Beitrag, ein Abstract, eine README). Löse jetzt jede Unstimmigkeit – eine Folie, die 38 sagt, während der Beitrag 36 sagt, zerstört Vertrauen, und diese Unstimmigkeiten entstehen normalerweise, wenn zwei Stellen "dieselbe" Zahl unterschiedlich berechnen (unterschiedliche Stichprobengröße, unterschiedlicher Schwellwert).
• Notiere die Datenaufteilung: Was wurde verwendet, um die Methode zu entwickeln, im Vergleich zu dem, was zurückgehalten wurde, um sie zu testen. Die Folie muss dies sagen, denn "Gilt das Ergebnis auch für Daten, die es nie gesehen hat?" ist die erste Frage, die ein technischer Leser stellt.
• Zwei Modi:
  • Datenmodus (Ergebnisse, Modelle, CSVs, Logs existieren): Das Zeichnungsskript lädt sie und berechnet jede Zahl zur Renderzeit.
  • Quellenmodus (nur Text): Jede Zahl wird aus der Quelle kopiert, und das Faktenblatt zitiert, woher sie stammt (Seite, Tabelle, Abbildung). Erfinde oder runde keine Zahlen über das hinaus, was die Quelle angibt.

Speichere das Faktenblatt neben der Folie (<name>_facts.md), damit spätere Bearbeitungen konsistent bleiben.

Schritt 1 – Finde die Geschichte (3–6 nummerierte Karten)

Schreibe einen Satz, der jede Frage beantwortet. Jede Antwort wird zu einer Karte:

1. Entdeckung / Kontext – was wurde bemerkt, oder was ist die Umgebung.
2. Problem – was ist falsch oder fehlt, gemessen. Wenn es mehrere Probleme gibt, nenne sie (Problem A, Problem B). Gib an, was angegangen wird und was bewusst nicht angegangen wird, mit Begründung – ein Leser, der einen schwachen Punkt im Diagramm sieht und keine Erklärung, nimmt einen Fehler an.
3. Methode – das Rezept für einen Fall, als Schritte.
4. Von einem Fall zu allen Fällen – wie das Rezept überall angewendet wurde, die Regeln, die entschieden haben, wie viele, und die Zählungen. Paare jede Korrektur mit dem Problem, das sie löst ("Korrektur A → Problem A").
5. Ergebnis + Lehre – was sich geändert hat, wie sicher wir sind, was es lehrt.

Verschmelze Karten, die dasselbe aussagen (redundante Karten wurden bei jeder Überprüfung entfernt). Bei einer kleinen Eingabe können die Karten 3 und 4 verschmelzen, oder die Folie kann 3 Karten haben: Problem → Methode → Ergebnis. Niemals mehr als 6 – darüber hinaus ist es eine Präsentation, keine Folie.

Schritt 2 – Überschrift

Eine oder zwei Zeilen oben: eine überraschende Tatsache + die ergriffene Maßnahme, z. B. "N der M Teile taten nichts. Also bekamen sie eine Aufgabe." Die Überschrift ist das, was jemanden zum Anhalten bringt; die Karten sind das, was sie vertrauen lässt. Die Zahlen in der Überschrift stammen aus dem Faktenblatt / den Skriptvariablen, niemals von Hand eingegeben.

Schritt 3 – Kartengerüst (gleich für jede Karte)

• Nummer + Akzentfarbe. Jede Karte hat eine große Nummer (1–5) und ihre eigene Akzentfarbe, die für den Rahmen und die Hervorhebungen verwendet wird. Nummern geben die Lesereihenfolge vor; Farben ermöglichen es späteren Karten, darauf zurückzuverweisen ("die 11 Detektoren aus Karte 4").
• Titel = die Frage, die die Karte beantwortet.
• Ein fetter Kernaussagesatz = die Antwort.
• Eine Hauptabbildung. Die Methodenkarte kann ein Raster von Schrittzellen verwenden; die Ergebniskarte kann ein Diagramm plus ein Erklärungsfeld verwenden.
• Datenlabel – welche Daten diese Karte verwendet und warum diese Daten ("18.000 von 60.000 Trainingsbildern (30%) – der Rest blieb unsichtbar, damit der endgültige Check fair ist").
• Kurze Fußnote – nur Einschränkungen. Begründungen gehören niemals in die Fußnote (siehe Schritt 4).

Schritt 4 – Methodenkarte: WAS / Bild / WARUM-Zellen

Teile die Methode in 3–5 nummerierte Zellen auf (ein 2×2-Raster bei 4 Zellen). Jede Zelle hat die gleichen drei Bänder, von oben nach unten:

1. Beschriftung (WAS) – eine konkrete Aktion, die sagt, was womit verglichen wird: "Vergleiche ein NEUES Bild (eines, das es nie gesehen hat) mit dem Muster aus Schritt 2", nicht "es wird abgeglichen".
2. Bild – aufgebaut aus echten Beispielen aus den Daten oder der Quelle: tatsächliche Eingaben, das tatsächliche Zwischenergebnis, tatsächliche Bewertungen. Echte Beispiele machen einen abstrakten Schritt glaubwürdig; ein generisches Symbol lehrt nichts.
3. WARUM-Box – volle Breite, feste Höhe, sichtbar gestaltet (getönter Hintergrund, "WARUM?"-Label). Sie erklärt, warum der Schritt funktioniert.

Das WARUM muss im Bild prominent sein. Bei der Überprüfung wurden Begründungen in Fußnoten jedes Mal übersehen, und der Leser musste wiederholt fragen. Beantworte in den Zellen die Fragen, die die Leser stellen werden:

• Warum diese Wahl anstelle der naheliegenden? (z. B. warum den Durchschnitt der richtigen Klasse abziehen)
• Was wird dadurch NICHT beeinflusst, und warum nicht? (z. B. "es kann nur '3' senken; wenn eine andere Klasse bereits gewinnt, ändert sich nichts")

Zeige den Mechanismus als vorher → nachher: ein kleines Feld mit Bewertungen/Zuständen vorher, ein Pfeil, das Feld nachher, mit ✓/✗ auf dem Gewinner und einer kurzen Anmerkung auf dem Pfeil ("der Zweitplatzierte gewinnt"). Wenn ein Feldtitel nicht darunter passt, setze ihn daneben.

Wenn ein Bild die Realität vereinfacht (es zeigt Pixel, während die tatsächliche Berechnung interne Merkmale verwendet), sage dies in der Fußnote – Ehrlichkeit über Vereinfachung kostet eine Zeile und verhindert einen Kommentar "so funktioniert das nicht".

Markiere ein ausgearbeitetes Beispiel mit "Beispiel:" und nenne die allgemeine Regel ("gleiches Rezept für alle 30 Detektoren"), sonst denken die Leser, die Methode decke nur diesen einen Fall ab.

Schritt 5 – Mache jede Zahl nachvollziehbar

• Zeige den Ursprung jeder Zahl als sichtbare Kette: "21 Beispiele → 3 Stile → 3 Detektoren", "11 + 19 = 30 von 36 (6 übrig)". Summen müssen sichtbar aufgehen, und Reste benötigen einen Grund.
• Nenne die Auswahlregeln und Schwellwerte, die die Zählungen erzeugt haben ("ein Stil benötigt ≥2 Beispiele", "Fehler mit <3 Beispielen übersprungen, da zu wenige zum Lernen").
• Wenn Daten aus verschiedenen Quellen stammen (gelabelt vs. gemined, gemessen vs. geschätzt), zeige dies visuell (dunkle vs. helle Balken) mit einer Legende.
• Erkläre jede Notation beim ersten Auftreten ("×N = N Stil-Detektoren für diesen Fehler").
• Im Datenmodus berechnet das Skript jede Zahl; Textzeichenfolgen verwenden die Variablen (f-Strings / Vorlagenwerte). Handgetippte Zahlen geraten aus dem Takt mit den Daten – dies verursachte eine echte falsche Folie.

Schritt 6 – Ehrliches Ergebnis, jede Änderung erklärt

• Vorher → Nachher auf Daten, die niemals zur Entwicklung der Methode verwendet wurden; bestätige auf einem zweiten unbenutzten Satz, wenn einer existiert.
• Gib Gewinne und Verluste an ("34 behoben, 9 kaputt gemacht"). Ein Ergebnis mit nur Gewinnen wirkt wie Rosinenpickerei.
• Statistiken in einfachen Worten ("etwa 6 von einer Million durch Zufall"), mit der technischen Form klein oder in der Fußnote.
• Ein Änderungsdiagramm pro Element (nachher − vorher, farbig positiv / negativ / null) plus ein Panel "Warum sich jedes geändert hat": warum Gewinne auftraten, warum Verluste auftraten, etwaige positive Nebeneffekte. Die Auflistung eines Verlustes ohne seine Begründung lädt zur schlimmsten Interpretation ein.

Schritt 7 – Klare, konsistente Wörter

• Definiere jeden Begriff bei der ersten Verwendung in wenigen einfachen Wörtern oder ersetze ihn durch ein einfaches Wort.
• Ein Wort pro Konzept auf der gesamten Folie ("vorhergesagt" überall, nicht manchmal "geantwortet").
• Keine internen Spitznamen ("Satz A", "der Twist", "glücklicher Nebeneffekt", "×3"), es sei denn, sie sind auf der Folie definiert.
• Jede Behauptung muss mit ihrem Diagramm übereinstimmen. Wenn das Diagramm etwas Seltsames zeigt, das der Text nicht anspricht, sprich es an.

Schritt 8 – Legenden und Farbe

• Jede Farbe, Schattierung, jeder Pfeil und jedes Symbol wird dort erklärt, wo es erscheint. Divergierende Bilder erhalten "rot = nur in X, blau = nur in Y".
• Eine Farbbedeutung auf der gesamten Folie: z. B. rot = Problem/entfernt, grün = behoben/gut, grau = neutral. Kartenakzentfarben sind von diesen semantischen Farben getrennt.
• Gruppierte Elemente (Stile eines Fehlers, Varianten eines Schritts) sitzen in sichtbaren Boxen, damit Gruppen nicht verschwimmen.

Schritt 9 – Fazit- und Lehrbanner

• Fazitbanner (grüne Tönung): was gezeigt wurde, einschließlich seiner Größe und Grenzen ("kleiner, aber echter Gewinn, der auf neuen Daten Bestand hat").
• Lehrbanner (unten auf der Folie): was der Leser auf andere Probleme übertragen kann.

Schritt 10 – Layout

• 16:9 (z. B. 16×9 Zoll bei 150 dpi oder eine 1600×900 Pixel Leinwand). Karten werden in Story-Reihenfolge von links nach rechts gelesen.
• Größe der Karten nach Inhalt – die Methodenkarte ist normalerweise am breitesten. Keine großen leeren Bereiche: Wenn eine Karte Platz hat, verbreitere ihr Diagramm oder verschiebe ihr Textpanel in den Raum.
• Kein überlappender Text; Beschriftungen bleiben in ihren Boxen. Lange Zeilen umbrechen, anstatt Schriftarten unter die Lesbarkeit auf dem Telefon zu schrumpfen (≈7,5 pt bei 16×9 Zoll ist die Untergrenze).
• Lies references/matplotlib-recipes.md (PNG) oder references/html-recipes.md (HTML) für Layout-Code. scripts/slide_kit.py bietet matplotlib-Hilfsfunktionen (Karten, Schrittzellen, WARUM-Boxen, Vorher/Nachher-Bewertungspanels, Banner, PNG+JPG-Export) – importiere es, anstatt sie neu zu schreiben.

Schritt 11 – Rendern, prüfen, korrigieren, wiederholen

1. Rendere das Bild.
2. Betrachte das tatsächliche Bild – öffne das PNG und zoome in jede Karte (schneide sie ggf. aus). Code, der "eigentlich" passen sollte, passt oft nicht; Überlappungen und abgeschnittener Text sind nur im Rendering sichtbar.
3. Gehe references/checklist.md Karte für Karte durch, als Junioringenieur, der es zum ersten Mal sieht.
4. Korrigieren, erneut rendern, erneut prüfen. Zeige dem Benutzer keine Folie, die die Checkliste nicht besteht.

Schritt 12 – Varianten und Endkontrolle

• Detailierte Version für technische Leser (alle Zahlen). Biete eine einfache Version für ein breites Publikum an: gleiche Geschichte, weniger genaue Zahlen.
• Exportiere eine JPG-Kopie (keine Transparenz) für LinkedIn/X.
• Überprüfe jede externe Behauptung oder jedes Zitat, das auf der Folie oder in einem Begleitbeitrag erscheint, vor der Veröffentlichung; markiere alles, was du nicht verifizieren konntest.
• Liefere: das PNG (+ JPG), das Zeichnungsskript oder die HTML-Quelle und das Faktenblatt. Erwähne, dass linkedin-arabic-science-post, tweet-post oder figure-animator aus der fertigen Folie einen Beitrag oder eine animierte Version erstellen können.