Stilregeln für Leser, denen das Thema neu ist
Konkret vor abstrakt, Begriffsbudget je Zwischenabschnitt mit Untergrenze, Interna in „Unter der Haube“ (Wissensthemen: „Vertiefung“), frühere Begriffe kurz in Erinnerung rufen. Prüfer kontrolliert das. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
@@ -15,6 +15,12 @@ Ein deutschsprachiges Sachbuch, das **Verständnis** vermittelt: Wie ist die Sac
|
||||
- Hat ein Codebeispiel eine Ausgabe, steht die tatsächliche Ausgabe des eigenen Testlaufs als ```text-Block direkt darunter, gekürzt auf das Wesentliche (höchstens etwa 10 Zeilen).
|
||||
- Strukturdiagramme: Baum-, Ablauf- und Zustandsstrukturen, die aus Quellcode oder Doku belegt sind, als Textdiagramm mit Kästen und Pfeilen in einem ```diagramm-Block (Zeichen ┌─┐│└┘├┤┬┴ und ▶ ▼, höchstens 60 Zeichen breit, höchstens eines je Abschnitt). Jedes Element im Diagramm kommt auch im Text vor. Keine Illustrationen, keine Szenen, nichts Erfundenes.
|
||||
|
||||
## 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.
|
||||
- Ein Begriff, der in einem früheren Kapitel eingeführt wurde, wird bei Wiederverwendung mit einem halben Satz in Erinnerung gerufen, nicht vorausgesetzt.
|
||||
|
||||
## Aufbau jeder Kapiteldatei (Markdown)
|
||||
```
|
||||
# Kapitel N – Titel
|
||||
|
||||
Reference in New Issue
Block a user