Was macht explain-it?
Verwandle untersuchten Code in eine kleine statische HTML-Seite, die ein kluger Leser ohne Kontext zu diesem Codebase nachvollziehen kann: eine Startseite, die das mentale Modell aufbaut, eine Seite pro Thema und eine Seitenleiste, die sie verbindet.
Das Ziel: „Einfache Sprache, die weder zu einfach noch zu schwierig ist.“ Nie herablassend; nie Repo-Wissen voraussetzen.
Arbeitsablauf
1. Untersuchen, bevor du erklärst
Erkläre nie Code, den du nicht gelesen hast. Lies für jedes Thema den tatsächlichen Quellcode: die geänderten Zeilen, die umschließende Funktion und mindestens einen Aufrufer, damit du die Frage „Wann wird dieser Code überhaupt ausgeführt?“ mit einer wahren Geschichte beantworten kannst. Wenn eine Behauptung von jemand anderem stammt (z. B. ein Review-Kommentar, ein Issue), überprüfe sie zuerst am Code und sage es, wenn sie nicht zutrifft.
2. Die Seite planen
- Eine Startseite (
index.html): der Primer. Sie baut das mentale Modell des Systems in ca. 2 Minuten auf und verlinkt auf jede Themenseite. - Eine Seite pro Thema (
01-<slug>.html,02-<slug>.html, …): jede Seite erklärt eine Änderung, einen Fehler, eine Entscheidung oder ein Subsystem. 3–7 Seiten sind der optimale Bereich; fasse Themen zusammen, statt ~9 zu überschreiten. - Eine gemeinsame Seitenleiste auf jeder Seite, die alle Seiten in Lesereihenfolge
auflistet, wobei die aktuelle Seite hervorgehoben ist. Seiten sind einfache
Dateien, die mit relativen
<a href>verlinkt sind – die Seite muss direkt aus dem Dateisystem (file://) funktionieren, also keine Router, kein Build-Schritt, kein externes JS.
Frage den Benutzer nur, wo der Ordner abgelegt werden soll, wenn kein Ort offensichtlich
ist; andernfalls erstelle einen sinnvoll benannten Ordner neben der Arbeit (z. B.
docs/explainers/<topic>/) und teile mit, wo du ihn abgelegt hast.
3. Jede Seite schreiben
Folge references/writing-guide.md für die Methode – lies es, bevor du deine erste
Seite schreibst. Die unverhandelbaren Punkte:
- Primer zuerst. Die Startseite führt jedes benötigte Domänenkonzept ein, jeweils mit einer konkreten Metapher (z. B. „Ein Release ist eine Fotokopie; ein laufender Job pinnt eine Fotokopie“). Führe eine Metapher einmal ein und verwende sie dann überall wörtlich wieder. Staple niemals zwei Metaphern für ein Konzept.
- Jedes Thema in der Laufzeit verankern. Jede Themenseite beginnt mit einer „Wann wird dieser Code eigentlich ausgeführt?“-Geschichte: 2–4 Akteur-Schritte (Benutzer tut X → System führt Funktion Y aus → der winzige Job darin). Echte Funktionsnamen in Code-Schrift, parallel zur – nie anstelle der – einfachen Erzählung.
- Die Änderung als Diff zeigen. Alter vs. neuer Code in rot/grün Diff-Blöcken mit dem Dateipfad im Header, auf das Wesentliche reduziert, mit 1–3 Inline-Kommentaren, die auf das Warum hinweisen – nicht das Was beschreiben.
- Das „Warum“ quantifizieren. „Langsam“ ist verboten; „Hunderte KB pro Anfrage, ~99% der Zeit für nichts“ ist der Standard. Gleiches für Risiko: Nenne den konkreten Eingabe-/Zustand und das falsche Ergebnis.
- Fehler von Entscheidungen trennen. Wenn etwas eine vertretbare Produktentscheidung und kein Defekt ist, präsentiere es als Entscheidung mit dem Kompromiss, nicht als Fehler.
- Die Startseite mit einer Tabelle beenden: eine Status-Tabelle jedes Elements (erledigt / vorgeschlagen / zurückgestellt) mit seiner Position im Codebase.
4. Das HTML bauen
Kopiere references/site-template.html als Ausgangspunkt für jede Seite – es enthält
die Design-Tokens, die Seitenleiste und ein funktionierendes Beispiel jeder Komponente
(Story-Block, Hinweis, Diff-Block, Status-Tabelle, Pills). Dann:
- Halte jede Seite vollständig in sich geschlossen (alles CSS inline in der Seite).
Die Seitenleiste wird in jede Seite kopiert, wobei das aktuelle Element mit
class="on"markiert ist. - Folge
references/design-system.mdfür Tokens und Komponentenregeln. Behalte die Farbpalette, Abstände und den Schriftgrößen-Maßstab bei, damit mehrseitige Seiten wie ein System aussehen. Die Vorlage enthält einen Hell/Dunkel-Umschalter und eine einklappbare Seitenleiste – übernimm beide in jede Seite, anstatt sie wegzulassen. - Keine externen Abhängigkeiten außer dem Google-Fonts-Link, der bereits in der Vorlage ist (der Font-Stack fällt offline sauber zurück) und kein JS über das Theme-Toggle-Snippet der Vorlage hinaus.
5. Vor der Übergabe überprüfen
Öffne oder rendere die Startseite und mindestens eine Themenseite (oder lies sie noch einmal) und überprüfe: Jeder Seitenleisten-Link funktioniert, jeder im Text erwähnte Code-Identifier existiert im Codebase mit der genauen Schreibweise, jeder Diff kompiliert konzeptionell gegen die echte Datei, und die Status-Tabelle ist aktuell. Teile dann dem Benutzer den Ordnerpfad mit und öffne die Startseite für ihn, wenn es die Umgebung erlaubt.
Häufige Fallstricke
- Aus der Erinnerung an das Gespräch statt aus dem Code erklären – der Erklärer übernimmt jede veraltete Behauptung. Lies die Quelle erneut.
- Metaphern-Drift: sie auf einer Seite „Fotokopie“ und auf der nächsten „eingefrorene Kopie“ nennen. Ein Begriff, überall.
- Diff-Blöcke, die 60 Zeilen wörtlich einfügen. Reduziere auf das Wesentliche; behalte 2–4 Kontextzeilen darum herum.
- Prosa, die Diff Zeile für Zeile nacherzählt. Das Diff zeigt was; die Prosa trägt nur warum es wichtig ist und wann es läuft.
- Eine Seitenleiste, die es nur auf der Startseite gibt. Jede Seite trägt die vollständige Seitenleiste.
- Babysprache („der Computer merkt sich Dinge in einer speziellen Box“). Der Leser ist klug – er kennt nur dieses eine Codebase nicht.