Logo

Effektive Kursinhalte schreiben

Inhalte erstellen

Effektive Kursinhalte schreiben

Kursinhalte auf git.nrw entstehen in Markdown. Diese Lektion fasst die nötige Syntax zusammen und beschreibt, was eine gut lesbare Lektion ausmacht: Struktur, Tonalität und der Umgang mit Reveal-Fragen.

Grundlagen von Markdown

Markdown ist eine leichtgewichtige Auszeichnungssprache. Die wichtigsten Elemente:

Überschriften

# erzeugt Überschriften. Mehr #-Symbole ergeben kleinere Überschriften:

# Hauptüberschrift
## Unterüberschrift
### Kleinere Unterüberschrift

Listen

Ungeordnete Listen beginnen mit - oder *, geordnete Listen mit Zahlen:

- Punkt 1
- Punkt 2

1. Erster Punkt
2. Zweiter Punkt

Codeblöcke

Inline-Code steht in einfachen Backticks, Codeblöcke in dreifachen Backticks:

Mit `git commit` übernehmen Sie Ihre Änderungen.

git add .
git commit -m "Ihre Commit-Nachricht"
git push origin main

[Link-Text](URL)
![Alternativtext](Bild-URL)

Bewährte Praktiken für Kursinhalte

  1. Mit einem kurzen Einstieg beginnen, nicht mit einer Formel: Nicht in jeder Lektion derselbe Satz wie „In dieser Lektion lernen Sie …“. Ein kurzer, konkreter Einstiegssatz ist meist besser.

  2. Überschriften nach Inhalt benennen: Eine Überschrift sagt, was im Abschnitt steht („Setup-Dateien“, „Warum die Unterscheidung wichtig ist“). Schema-Überschriften wie „Goal“ oder „Do“ vermeiden.

  3. Klare, prägnante Sprache: Konzepte in einfachen Worten erklären, Fachbegriffe nur dort, wo sie nötig sind.

  4. Inhalte in Abschnitte gliedern: Überschriften teilen den Inhalt in logische Abschnitte.

  5. Beispiele einfügen: Praktische Beispiele veranschaulichen Konzepte.

  6. Visuelle Elemente nutzen: Diagramme, Screenshots oder andere visuelle Hilfen fördern das Verständnis.

  7. Mit einer Regel schließen, dann Check: Die Lektion direkt vor ## Check zu einer verdichteten Regel oder kurzen Liste zusammenfassen, ohne eigene Überschrift. ## Check ist der letzte Block der Lektion.

  8. Interaktive Fragen für Selbsterklärung nutzen: Reveal-Fragen eignen sich, wenn Lernende einen Begriff erklären, zwei Dinge unterscheiden oder eine Diagnoseentscheidung begründen sollen.

  9. Reveal-Antworten als echte Antworten schreiben: Formulierungen wie „Erklären Sie, warum …“ oder „Nennen Sie …“ gehören in die Frage, nicht in die Antwort. Im Reveal steht bereits eine kurze Musterantwort.

  10. Abschnitte rahmen, nicht jede Lektion: {{< objectives >}} an den Anfang der ersten Lektion eines Abschnitts, {{< keypoints >}} ans Ende der letzten. Nur Lektionen ab 10 Minuten bekommen ein eigenes Paar.

Tonalität und Sprache

Lernende werden gesiezt, der Ton bleibt sachlich. Anweisungen, die Lernende ausführen sollen, stehen im Imperativ („Führen Sie aus:“); alles andere beschreibt. Code, CLI-Ausgaben, Dateinamen und die Überschrift ## Check bleiben in beiden Sprachen englisch. Alle anderen Überschriften stehen in der Sprache der Lektion.

Für deutsche Lektionen gelten drei zusätzliche Regeln: mit einem beschreibenden Satz einsteigen statt mit einem übersetzten Imperativ, „Sie“ sparsam einsetzen und Arbeitslisten im Infinitiv schreiben („das Projektverzeichnis anlegen“). Die vollständigen Regeln und die Terminologietabelle stehen im Repository unter docs/course-writing-guide.md .

Empfohlenes Lektionsmuster

Ein praxistaugliches Standardmuster sieht so aus:

# Titel der Lektion

Ein bis zwei Sätze, die die Lektion einordnen.

## Überschrift nach Inhalt benannt

Erklärung, Beispiele und Schritte.

## Typische Fehler

{{< troubleshoot problem="Ein typischer Fehler" >}}
Was stattdessen zu tun ist.
{{< /troubleshoot >}}

Die verdichtete Regel dieser Lektion als kurzer Absatz oder Liste.

## Check

{{< reveal question="Eine Frage, die Lernende jetzt beantworten können sollten" >}}
Eine vollständige Musterantwort.
{{< /reveal >}}

Die erste Lektion eines Abschnitts beginnt direkt nach dem Einstieg mit {{< objectives >}}, die letzte Lektion eines Abschnitts endet nach ihrem ## Check mit {{< keypoints >}}. Bei Abschlusslektionen kann es sinnvoll sein, einen Abschnitt „Ihr Ergebnis verifizieren“ von ## Check zu trennen.

Reveal-Fragen gut einsetzen

Reveal-Fragen sind besonders nützlich, wenn sie Lernende dazu bringen, etwas Wichtiges selbst zu erklären:

  • Setup von generiertem Zustand unterscheiden
  • begründen, warum ein Validierungsschritt wichtig ist
  • entscheiden, welche Datei oder welcher Befehl zuerst geprüft werden sollte

Weniger hilfreich sind sie, wenn nur isoliertes Faktenwissen abgefragt wird.

Gute Reveal-Frage:

{{< reveal question="Warum sollten Sie generierten Zustand prüfen statt ihn zu bearbeiten?" >}}
Weil der generierte Zustand dokumentiert, was das Werkzeug tatsächlich erzeugt hat, und Ihnen hilft, das Ergebnis zu verifizieren.
{{< /reveal >}}

Schwache Reveal-Frage:

{{< reveal question="Warum sollten Sie generierten Zustand prüfen statt ihn zu bearbeiten?" >}}
Erklären Sie, warum generierter Zustand wichtig ist.
{{< /reveal >}}

Übung: Eine Lektion schreiben

  1. eine der Lektionsdateien aus der vorherigen Übung auswählen
  2. den Inhalt mit der Markdown-Syntax und den besprochenen Praktiken schreiben
  3. mindestens einen Codeblock, eine Liste und ein Bild einfügen
  4. festlegen, wo die Lektion in ihrem Abschnitt steht und ob sie mit Lernzielen beginnt oder mit Key Points endet
  5. für Reveal-Fragen vollständige Musterantworten schreiben

Die nächste Lektion behandelt Medien und Ressourcen für den Kurs.

Optionales Feedback