creator/templates/Format/Section.md

SECTION-AUFBAU

Jeder Baustein ist ein kleiner, eigenständiger Lern-Guide: er stellt EIN Konzept vor, erklärt es von Grund auf und macht es nutzbar. Zielgruppe: ein Junior-Entwickler, der das Thema NEU lernt und KEIN Vorwissen mitbringt. Du holst ihn ab und bringst ihm die Sache bei. Eine Section ist kein Stichwort-Zettel zum Nachschlagen.

Aufbau je Baustein — drei Beats, fließend ineinander, OHNE Zwischenüberschriften:

1. Einordnung (PFLICHT, der Ankerpunkt) — welches Problem löst der Baustein, wozu braucht man ihn? Knüpfe an etwas Bekanntes/Alltägliches an, bevor das Neue kommt. Ohne diesen Anker steht ein Neuling im Leeren. Nie weglassen.
2. Erklärung — was es ist UND wie/warum es funktioniert. Alltagssprache, von der Intuition zum Detail. JEDEN Fachbegriff beim ersten Auftreten in einem Halbsatz auflösen — auch Begriffe aus dem Section-Titel oder anderen Bausteinen NIE als bekannt voraussetzen. Eine Analogie oder ein Bild ist erlaubt und oft besser als eine Definition. „Wie"-Abläufe Schritt für Schritt zeigen (nicht nur das Ergebnis nennen). Kleine Beispiele/Mini-Snippets dürfen schon hier mitten im Text stehen, wo sie einen Punkt sofort greifbar machen.
3. Beispiel(e) — das Konzept konkret gemacht (siehe BEISPIELFORMAT).

LESBARKEIT — wichtiger als Kürze:

• Kurze Sätze: eine Aussage pro Satz. Richtwert höchstens ~20 Wörter, nie über 25. Keine Schachtelsätze mit mehreren Einschüben (Gedankenstrich-Einschübe vermeiden).
• Kurze Absätze: eine Idee pro Absatz. Lieber zwei kurze Absätze als ein dichter Block. Keine Textwand.
• Aufzählungen (Schritte, Optionen, Anforderungen, mehrere gleichrangige Punkte) als Markdown-Liste mit -, NIE in einen langen Aufzählungssatz pressen.
• Wenige neue Fachbegriffe pro Section. Jeden beim ersten Auftreten in Alltagssprache auflösen. Lieber eine Stufe einfacher erklären als mehr Fakten stapeln.
• Im Zweifel ein Satz mehr und klar — statt verdichtet. Verständlichkeit schlägt Knappheit.

LÄNGE — so lang wie nötig:

• KEIN festes Wortlimit. Die Länge richtet sich nach der Schwierigkeit des Konzepts.
• Verständnis-Test: Versteht ein NEULING das Konzept allein aus dieser Section, ohne anderswo nachzulesen? Wenn nein → einen Schritt mehr erklären (Warum + Wie), NICHT verdichten. Diese Section trägt die volle Tiefe selbst — es gibt keine zweite Ausbaustufe mehr, die nachliefert.
• Weglassen: Füllsätze, Einleitungsfloskeln („In diesem Abschnitt…"), Wiederholungen, Fazit. Nicht jeden Randfall nennen — das Übliche erklären, seltene Varianten in die Beispiele.

BEISPIELFORMAT — am Thema ausrichten, nicht pauschal an Code:

• Code-/Tool-Thema (Sprache, Framework, CLI, Konfiguration): Codeblock mit Sprachangabe, wenige Zeilen, Minimalbeispiel.
• Sprach-Thema (Vokabeln, Grammatik, Formulierungen): 1–3 Beispielsätze oder ein Mini-Dialog, fremdsprachiger Teil kursiv, deutsche Übersetzung in Klammern wo nötig.
• Konzept-Thema (Psychologie, Kommunikation, Methoden, Theorie, Mathe): ein Mini-Szenario in 2–4 Sätzen (Situation → Anwendung → Wirkung), ein Schema oder eine durchgerechnete Formel mit kleinen Zahlen. Mischthemen: pro Beispiel das Format wählen, das den Punkt am direktesten zeigt. Ein Beispiel ist immer KONKRET (echter Code, echte Sätze, echte Situation) — nie die Beschreibung, was ein Beispiel zeigen würde. Mehrere Beispiele benennen ihre Variante: in Code als Kommentar in der Code-Syntax (z. B. <!-- Einzelner Absatz -->, // Mit Default-Wert), in Prosa als vorangestelltes fettes Label (z. B. Höfliche Bitte:). Bei nur einem Beispiel ist kein Label nötig.

Jede Section ist ATOMAR: allein verständlich, ohne dass der Leser eine andere Section gelesen hat. Test: Ergibt der Text Sinn, wenn man NUR diese Section liest? Verweise auf andere Bausteine sind erlaubt, ihr Inhalt darf aber nie vorausgesetzt werden — benutzte Begriffe in einem Halbsatz auflösen.

Tonalität: klares, direktes Deutsch. Du erklärst, du referierst nicht. Praxisorientiert, ohne Füllsätze.

Markdown im Section-Body: erklärende Absätze in normalem Text, Aufzählungen als Markdown-Liste (-), inline-code für Bezeichner, Codeblöcke mit Sprachangabe NUR für Code-Beispiele — Beispielsätze, Dialoge und Szenarien als normaler Text, NIE in einen Codeblock zwingen. fett sparsam für Kernaussagen und Beispiel-Labels. Keine eigenen Überschriften außer ### Beispiel bzw. ### Beispiele vor den Beispielen.

Mathematik IMMER als LaTeX schreiben: inline zwischen $…$ (z. B. $\Sigma^*$, $L \subseteq U$, $k = 3$), abgesetzte Formeln zwischen $$…$$. KEINE Unicode-Sonderzeichen als Mathe-Ersatz (nicht x₁, ¬, ∨, ≤ — stattdessen $x_1$, $\neg$, $\lor$, $\le$) und keine nackten Formeln ohne $. Außerhalb von Mathe normaler Text.

Beispiel einer fertigen Section (Code-Thema, nur der Body):

Arrays lösen ein simples Problem: Du willst viele Werte unter einem Namen halten, statt für jeden eine eigene Variable. In PHP gibt es zwei Sorten. Indizierte Arrays nummerieren die Werte durch ([0 => 'a']). Assoziative Arrays geben jedem Wert einen eigenen Schlüssel (['key' => 'wert']) — praktisch, wenn die Position egal ist, der Name aber zählt. Intern sind beide dasselbe: geordnete Hashmaps.

Beispiel

$preise = ['apfel' => 1.20, 'birne' => 1.50];
$preise['kirsche'] = 3.90;   // neuen Schlüssel ergänzen
echo $preise['apfel'];       // 1.2 — Zugriff über den Namen

So sieht der Alltag aus: Datenbankzeilen, Konfiguration, JSON landen fast immer in assoziativen Arrays.

Beispiel einer fertigen Section (Konzept-Thema, nur der Body):

Im Streit reden zwei oft aneinander vorbei, weil keiner sicher ist, ob er den anderen richtig verstanden hat. Paraphrasieren setzt genau hier an: Du wiederholst die Aussage des Gegenübers in eigenen Worten und fragst nach, ob das so stimmt. Das prüft dein Verständnis und nimmt Tempo aus dem Konflikt — der andere fühlt sich gehört, statt sich verteidigen zu müssen. Wichtig: Du bestätigst nicht den Vorwurf, du spiegelst nur die Botschaft dahinter.

Beispiel

A: „Nie hältst du dich an Absprachen!" B: „Du bist sauer, weil ich den Termin gestern verschoben habe — richtig?" B übernimmt nicht das Wort „nie", sondern benennt das konkrete Anliegen. Das öffnet das Gespräch, statt es zu eskalieren.

Beispiel einer fertigen Section mit Aufzählung (Liste statt Aufzählungssatz):

Bevor du Shopware installierst, muss dein Server die Software tragen können. Sonst bricht die Installation ab. Shopware 6 braucht ein paar feste Bausteine:

• PHP 8.2, 8.3 oder 8.4 — die Sprache, in der Shopware läuft.
• MySQL ab 8.0.17 oder MariaDB ab 10.11 — die Datenbank für deine Artikel und Bestellungen.
• Composer ab 2.2 — lädt die PHP-Bibliotheken, die Shopware mitbringt.
• Node.js 20+ — baut die JavaScript- und CSS-Dateien zusammen.

Beispiel

php -v          # PHP-Version prüfen
composer -V     # Composer-Version
node -v         # Node-Version

Stimmt eine Version nicht, aktualisierst du sie zuerst. Eine zu alte Version ist die häufigste Ursache für eine fehlgeschlagene Installation.