Stilregel: Interna streichen statt in „Unter der Haube“ verschieben
Interna kommen nur noch ins Buch, wenn sie ein sichtbares Verhalten erklären, und dann kurz im Haupttext. Der Prüfer streicht den Rest. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
@@ -18,7 +18,7 @@ Ein deutschsprachiges Sachbuch, das **Verständnis** vermittelt: Wie ist die Sac
|
||||
## Verständlichkeit für Leser, denen das Thema neu ist
|
||||
- Konkret vor abstrakt: Jeder neue Begriff bekommt zuerst eine Situation oder ein Beispiel aus dem Thema, dann die Erklärung, dann den Namen. Nicht mit der Definition beginnen.
|
||||
- Begriffsbudget: etwa 5 neue Fachbegriffe oder Klassen je Zwischenabschnitt. Braucht der Stoff mehr, einen weiteren Zwischenabschnitt anlegen. Zwischenabschnitte (###) 200–600 Wörter, nicht kleiner.
|
||||
- Interna trennen: Quellcode-Details, Server-Ebene, Speicherlayout, Registrierungsmechanismen, Herleitungen über das Nötige hinaus stehen in einem eigenen Zwischenabschnitt `### Unter der Haube` am Ende des Abschnitts (bei Wissensthemen `### Vertiefung`). Der Abschnitt muss ohne ihn verständlich sein; höchstens einer je Abschnitt. Dieser Teil wird gelesen, nicht übersprungen: Er erklärt den Mechanismus mit derselben Sorgfalt (Beispiel, Erklärung, Name), kein Nachschlagestil, kein Sammelbecken für Dichtes.
|
||||
- Interna weglassen: Quellcode-Details, Server-Ebene, Speicherlayout, Registrierungsmechanismen, Herleitungen über das Nötige hinaus kommen nicht ins Buch, auch nicht in einen eigenen Zwischenabschnitt. Einzige Ausnahme: Ein Internum, das ein sichtbares Verhalten erklärt, steht in zwei bis drei Sätzen im Haupttext an der Stelle, wo das Verhalten auftritt.
|
||||
- Zusammenhang ausschreiben: Jeder Satz knüpft erkennbar an den vorigen an. Den Begriff wiederholen statt „es“, „dies“, „dieser Mechanismus“. Wo ein Grund oder eine Folge vorliegt, steht sie im Text („weil“, „deshalb“, „dadurch“, „damit“). Kein Gedankensprung ohne Übergang; an jeder Absatzgrenze ein Brückensatz, der sagt, was der neue Absatz mit dem vorigen zu tun hat. Leser ohne Vorwissen können Lücken nicht selbst füllen.
|
||||
- Ein Begriff, der in einem früheren Kapitel eingeführt wurde, wird bei Wiederverwendung mit einem halben Satz in Erinnerung gerufen, nicht vorausgesetzt.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user