81 lines
8.1 KiB
Markdown
81 lines
8.1 KiB
Markdown
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.
|
||
|
||
Formeln brechen NICHT automatisch um — lange Mathe läuft sonst über den Rand. Darum:
|
||
- **Inline `$…$` nur für KURZE Symbole/Terme** — einzelne Variablen, Mengen, kurze Relationen (`$\Sigma^*$`, `$k = 3$`, `$x \notin L$`). NIE einen ganzen Ausdruck mit mehreren Teilen oder Sätzen inline (auch nicht in einem Listenpunkt).
|
||
- **Lange oder mehrteilige Formeln IMMER abgesetzt zwischen `$$…$$` auf eigener Zeile** — besonders Mengen-/Set-Builder-Definitionen (`\{ … \mid … \}`). Nicht inline, nicht in eine Aufzählung quetschen.
|
||
- **KEINE Prosa in `\text{…}`.** Bedingungen und Erklärungen als normalen deutschen Text NEBEN oder UNTER die Formel, nicht in sie hinein. Also nicht `$$L = \text{CLIQUE} = \{ u\#v \mid u \text{ kodiert die Adjazenzmatrix …}\}$$`, sondern die Formel knapp (`$$L = \{\, u\#v \mid \dots \,\}$$`) und die Bedeutung von `u`, `v` im Fließtext erklären.
|
||
- Lange Definitionen oder Gleichungsketten mit `$$\begin{aligned} … \\ … \end{aligned}$$` über mehrere Zeilen umbrechen.
|
||
|
||
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
|
||
```php
|
||
$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
|
||
```bash
|
||
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.
|