48 lines
8.5 KiB
Markdown
48 lines
8.5 KiB
Markdown
## Ziel
|
||
Ein deutschsprachiges Sachbuch, das **Verständnis** vermittelt: Wie ist die Sache aufgebaut, warum ist sie so, welche Befunde, Argumente oder Mechanismen stehen dahinter, was ist gesichert, was umstritten? Ziel ist eine breite Übersicht über alles Wichtige, nicht Vollständigkeit bis ins letzte Detail. Kein Tutorial, keine Referenz, kein Ratgeber.
|
||
|
||
## Form
|
||
- Sprache: Deutsch, korrekte Umlaute und ß, gut lesbare Sachbuchprosa. Keine direkte Anrede als Stilmittel; „wir“ sparsam.
|
||
- Satzbau: Sätze meist 14–18 Wörter, selten über 25, nie über 35. Höchstens ein Nebensatz je Satz, keine Semikolon-Ketten. Ein Gedanke je Satz; Bedingung und Folge dürfen zusammenstehen. Aktiv statt Nominalstil.
|
||
- Wortwahl: Verben statt Substantivierungen („prüfen“ statt „eine Prüfung vornehmen“, „wahrnehmen“ statt „die Wahrnehmung erfolgt“). Lange zusammengesetzte Wörter nur, wenn sie der Fachbegriff sind; sonst umschreiben oder bei der ersten Nennung erklären. Keine Füllwörter („grundsätzlich“, „im Wesentlichen“, „durchaus“).
|
||
- Code-Bezeichner im Fließtext nur, wenn der Satz von genau diesem Bezeichner handelt. Erst in Worten erklären, was etwas tut, dann den Namen nennen. Keine Aufzählungen von Methoden-, Eigenschafts- oder Klassennamen, weder im Satz noch als Tabelle: Solche Listen weglassen. Faustregel: höchstens ein Bezeichner je Satz, selten zwei.
|
||
- **Keine** Übungen, Selbsttests, Lernziele, Merkkästen, Checklisten, „Praxistipps“, Schritt-für-Schritt-Anleitungen als Selbstzweck, Literaturlisten.
|
||
- Jedes Kapitel endet mit einem eigenen Abschnitt `## N.M Merken`, nummeriert als letzter Abschnitt des Kapitels (hat das Kapitel 1.1 bis 1.4, heißt er `## 1.5 Merken`). Er ist ein Spickzettel zum Auffrischen nach Monaten: eine Bullet-Liste, je Zeile ein Begriff, Fakt oder System in der Form „Begriff: Kern“. Der Kern sind ein bis zwei ganze Sätze, die ohne das Kapitel verständlich sind (`- Antwortempfindlichkeit: Wie fein die Steuerung auf kleine Eingaben reagiert. Liegt am Programm, nicht am Gerät.`), kein Telegrammstil, keine Stichwortreihen. Fünf bis zehn Zeilen je Kapitel, etwa 80 bis 120 Wörter. Nur, was man sich merken soll; keine Beispiele, keine Herleitungen, keine Begründungen, keine Absätze, keine Abschnittsnummern, keine Fragen, nichts Neues, keine Begriffe, die das Kapitel nicht eingeführt hat. Der Abschnitt steht nicht in der Gliederung und zählt nicht zum Richtwert des Umfangs.
|
||
- Überwiegend Fließtext. Listen und Tabellen nur, wo sie echte Klarheit bringen – sparsam. Eine Tabelle vergleicht Varianten mit ihren Kosten; sie zählt nie Methoden, Eigenschaften, Konstanten oder Einstellungen auf.
|
||
- Kein Nachschlagewissen: keine Einstellungspfade (eine Projekteinstellung wird in Worten genannt, nicht als `pfad/zur/einstellung`), keine Standardwerte, Grenzwerte, Signaturen oder Parameterpositionen, die nur beim Bauen helfen. Keine Versionsnotizen („seit 4.3“, „in Godot 3 hieß“, „bis 4.2“): Das Buch beschreibt den Stand der Referenzversion, als hätte es nie einen anderen gegeben.
|
||
- Keine Autoren als Erzählgerüst: nicht „X beschreibt“, „X hält“, „X rät“, sondern die Sache selbst erklären und begründen. Der Erfinder eines Verfahrens wird höchstens einmal genannt, wenn das Verfahren nach ihm heißt. Keine Jahreszahlen, Daten, Lebensläufe oder Anekdoten ohne Erklärwert. Keine Testberichte im Text („Im Testlauf …“, „Das Skript läuft ohne Fehler“, „Ein Versuch zeigt“): Die Ausgabe spricht für sich.
|
||
- Fachbegriffe bei der ersten Nennung kurz erklären; englische Fachbegriffe nennen, wo sie üblich sind.
|
||
- Keine Quellenangaben im Text, weder in Klammern noch als „laut Dokumentation“: Quellen dienen der Prüfung, nicht dem Leser. Klassen und Befehle in `Code`-Formatierung.
|
||
- Keine Querverweise: keine Verweisklammern „(→ Abschnitt 8.2)“, keine Rückverweise („wie Abschnitt 3.2 zeigte“). Das Buch wird von vorn nach hinten gelesen; der Leser hat das Frühere gerade gelesen. Ein Thema wird nur in seinem Kapitel erklärt, anderswo höchstens in einem Halbsatz gestreift. Kommt ein Begriff vor seinem Kapitel vor, genügt ein Halbsatz wie „das erklärt Kapitel 8“.
|
||
- Wissensbücher (Buchtyp `wissen`) enthalten keinen Code, auch nicht für Rechnungen: Ein Ergebnis steht als Satz mit der einen Zahl, die es trägt. Befunde stehen als Aussagen über die Sache („Zu leichte Spiele langweilen schneller, als zu schwere frustrieren.“), nie als Studienreferat: keine Teilnehmerzahlen, Stichproben, Studiendesigns, Effektstärken, Gütekriterien, Methodenkritik, Forscherstreite oder Zählungen von Arbeiten. Unsicherheit in einem schlichten Satz („Ob …, ist offen.“). Keine Theoretiker als Gerüst, keine Fachgeschichte, keine Definitionsstreite des Fachs.
|
||
- Codebeispiele (falls das Thema Software ist): kurz (typisch 5–20 Zeilen), nur der Kern einer Idee, so wie er in einem Spielskript stünde (etwa `extends Node2D` mit `_ready()` oder `_process()`), mit Sprachangabe im Codeblock, im Text erklärt. Kein Testgerüst im Buch: kein `extends SceneTree`, kein `_init()`, kein `quit()`, keine Warteschleifen, Frame-Zähler, simulierten Eingaben, Fenstergrößen oder Hilfsfunktionen, die nicht abgedruckt sind. Zum Prüfen darf der Autor den Kern in ein Gerüst unter `arbeit/` stecken; abgedruckt wird nur der Kern.
|
||
- Code-Bezeichner (Variablen, Funktionen, Klassen, Signale, Knotennamen) sind englisch wie die Engine-API. Kommentare im Code und ausgegebene Texte sind deutsch.
|
||
- 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 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.
|
||
|
||
## Aufbau jeder Kapiteldatei (Markdown)
|
||
```
|
||
# Kapitel N – Titel
|
||
|
||
Einleitung: 2–4 Absätze, die ins Thema führen und die Leitfrage stellen.
|
||
|
||
## N.1 Titel des Abschnitts
|
||
Fließtext, ggf. mit ### Unterabschnitten.
|
||
|
||
## N.2 …
|
||
```
|
||
Überschriften exakt wie in GLIEDERUNG.md (Nummerierung beibehalten, ohne das Gewicht `(kurz)`/`(lang)`). Der Richtwert je Abschnitt steht in der Gliederung: `(kurz)` ≈ 800 Wörter, ohne Angabe ≈ 1.300, `(lang)` ≈ 2.000; ±20 % sind in Ordnung. Nicht auffüllen: Ist der Stoff erschöpft, ist der Abschnitt fertig. Abweichungen über 20 % im Bericht begründen.
|
||
|
||
## Korrektheit
|
||
- Jede Tatsachenangabe (Name, Jahr, Zahl, Bezeichner, Signatur, Versionsangabe, Studienergebnis) muss gegen die im Abschnitt „Quellen und Prüfung“ genannten Quellen geprüft sein. Nichts aus dem Gedächtnis übernehmen, ohne es zu prüfen; was sich nicht belegen lässt, vorsichtiger formulieren oder weglassen.
|
||
- Keine erfundenen Studien, Zitate, Zahlen, Klassen oder Optionen.
|
||
- Kontroversen und Replikationsprobleme fair darstellen.
|
||
- Keine persönlichen Daten an externe Dienste senden (keine E-Mail-Adressen als Parameter).
|