Regeln zum Schreiben von Software-Tutorials

xguru · 2025-01-15T10:41:02+09:00

Die meisten Software-Tutorials lassen wichtige Details aus oder enthalten versteckte Annahmen, die nicht zu den Erwartungen der Leser passen, sodass sie den Ablauf nicht reproduzieren können Mit ein paar einfachen Regeln ist es leichter als gedacht, ein hervorragendes Tutorial zu schreiben Regeln Für Anfänger schreiben Einen Titel formulieren, der ein klares Ergebnis verspricht Das Ziel in der Einleitung erklären Das Endergebnis vorab zeigen Code-Snippets schreiben, die per Copy-and-paste nutzbar sind In Befehlen lange Flags verwenden Benutzerdefinierte Werte und wiederverwendbare Logik trennen Den Aufwand für Leser reduzieren So schreiben, dass der Code jederzeit funktionsfähig bleibt Nur ein Thema vermitteln Klarheit vor Dekoration Abhängigkeiten minimieren Dateinamen eindeutig angeben Konsistente und beschreibende Überschriften verwenden Belegen, dass die Lösung funktioniert Ein vollständiges Beispiel verlinken Für Anfänger schreiben Der häufigste Fehler in Tutorials ist, Konzepte auf Anfänger-Niveau mit Begriffen auf Experten-Niveau zu erklären. Die meisten Menschen, die nach Tutorials suchen, sind Anfänger. Sie sind vielleicht keine Anfänger im Programmieren, aber Anfänger in dem Bereich, den sie lernen möchten Schreibe für Anfänger und vermeide möglichst Fachbegriffe auf Experten-Niveau Vermeide schwierige Begriffe und schreibe in einfacher Sprache, die Leser verstehen können In einem React-Tutorial sollte man zum Beispiel statt "JSX transpilation" eher etwas wie "eine einfache Webseite mit React erstellen" schreiben Einen Titel formulieren, der ein klares Ergebnis verspricht Der Titel sollte konkret vermitteln, was Leser durch das Tutorial lernen können Vermeide unklare oder vage Titel und beschreibe das erwartete Ergebnis eindeutig Beispiel: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView" Das Ziel in der Einleitung erklären Wenn Leser auf ein Tutorial klicken, interessieren sie sich bereits für das, was du sagst. Trotzdem musst du sie davon überzeugen, weiterzulesen Leser stellen sich dabei zwei Fragen Sollte ich mich für diese Technologie interessieren? Und wenn ja: Ist dieses Tutorial das Richtige für mich? Erkläre in der Einleitung knapp, warum die Technologie wichtig ist und warum das Tutorial nützlich ist Gib nützliche Informationen, die Interesse wecken, und vermeide vage Formulierungen Beispiel: Ein Docker-Tutorial sollte klar erklären, welches Problem Docker löst und welches Ergebnis zu erwarten ist Das Endergebnis vorab zeigen Zeige so früh wie möglich eine Demo oder einen Screenshot dessen, was Leser mit dem Tutorial erstellen werden Wenn das Endergebnis früh gezeigt wird, ist das Ziel klarer Zum Beispiel ein Screenshot des fertigen Produkts, der UI oder ein Beispiel der Funktionsweise Code-Snippets schreiben, die per Copy-and-paste nutzbar sind Schreibe so, dass Leser den Code leicht kopieren, in Editor oder Terminal einfügen und ausführen können Entferne unnötige Elemente wie das Terminal-Promptzeichen $ Vereinfache Befehle mit nicht-interaktiven Flags und verwende &&, damit bei einem Fehler abgebrochen wird In Befehlen lange Flags verwenden Verwende in Befehlen statt kurzer Flags besser aussagekräftige lange Flags, damit auch Anfänger sie leicht verstehen Statt -r besser --recursive Benutzerdefinierte Werte und wiederverwendbare Logik trennen Trenne im Code klar zwischen Werten, die Benutzer ändern sollen, und Code, den sie nicht ändern sollten Definiere benutzerdefinierte Werte über Umgebungsvariablen und verbessere so die Lesbarkeit des Codes Den Aufwand für Leser reduzieren Respektiere die Zeit der Leser, damit sie das Tutorial gern nutzen Ersetze langweilige Aufgaben durch Befehls-Snippets Beispiel: Statt Dateien manuell zu bearbeiten, das Problem per Befehl lösen So schreiben, dass der Code jederzeit funktionsfähig bleibt Beispielcode sollte immer ausführbar sein und auch in Zwischenschritten funktionsfähig bleiben Fehlerhafter oder nicht funktionierender Beispielcode verwirrt Leser Nur ein Thema vermitteln Ein Tutorial sollte sich auf ein einzelnes Thema konzentrieren und keine irrelevanten Technologien mischen Ein Tutorial zur Suchfunktion sollte zum Beispiel nicht unnötig AI-Technologien hinzufügen Klarheit vor Dekoration Leser interessiert es nicht, ob eine Spielzeuganwendung schön aussieht Reduziere unnötiges CSS oder Design-Elemente auf ein Minimum und konzentriere dich auf das Kernkonzept Vermittle Konzepte mit einfachem Code statt mit unnötig komplexen Beispielen Abhängigkeiten minimieren Halte die Zahl der Abhängigkeiten, die Leser installieren müssen, möglichst klein, damit das Tutorial zugänglicher wird Gib notwendige Abhängigkeiten klar an und nenne konkrete Versionen Dateinamen eindeutig angeben Weise Leser genau darauf hin, welche Dateipfade und Inhalte sie ändern müssen Statt zum Beispiel "Einstellungen zur config-Datei hinzufügen" sollte der vollständige Dateipfad und genauer Code angegeben werden, einschließlich der exakten Zeile, die bearbeitet werden muss Konsistente und beschreibende Überschriften verwenden Verwende strukturierte Überschriften, damit Leser das Tutorial leicht überfliegen können Gliedere das Tutorial mit Überschriften und formuliere sie so, dass sie die logische Struktur widerspiegeln Halte Format, Perspektive und Zeitform der Überschriften konsistent Belegen, dass die Lösung funktioniert Wenn ein Tutorial die Installation eines Tools oder die Integration mehrerer Komponenten erklärt, zeige auch, wie das Ergebnis verwendet wird Zeige Lesern visuell das funktionierende Ergebnis des installierten oder integrierten Tools Zeige zum Beispiel die erfolgreiche nginx-Seite und erkläre, wie man sie über die URL überprüft Ein vollständiges Beispiel verlinken Verlinke ein Repository mit dem gesamten Code des Tutorials, damit der komplette Ablauf nachvollzogen werden kann Teile den Code jedes Schritts in separate git-Branches auf, damit Leser jeden Schritt nachvollziehen können

(refactoringenglish.com)

70 Punkte von xguru 2025-01-15 | 11 Kommentare | Auf WhatsApp teilen

Die meisten Software-Tutorials lassen wichtige Details aus oder enthalten versteckte Annahmen, die nicht zu den Erwartungen der Leser passen, sodass sie den Ablauf nicht reproduzieren können
Mit ein paar einfachen Regeln ist es leichter als gedacht, ein hervorragendes Tutorial zu schreiben

Regeln

Für Anfänger schreiben
Einen Titel formulieren, der ein klares Ergebnis verspricht
Das Ziel in der Einleitung erklären
Das Endergebnis vorab zeigen
Code-Snippets schreiben, die per Copy-and-paste nutzbar sind
In Befehlen lange Flags verwenden
Benutzerdefinierte Werte und wiederverwendbare Logik trennen
Den Aufwand für Leser reduzieren
So schreiben, dass der Code jederzeit funktionsfähig bleibt
Nur ein Thema vermitteln
Klarheit vor Dekoration
Abhängigkeiten minimieren
Dateinamen eindeutig angeben
Konsistente und beschreibende Überschriften verwenden
Belegen, dass die Lösung funktioniert
Ein vollständiges Beispiel verlinken

Für Anfänger schreiben

Der häufigste Fehler in Tutorials ist, Konzepte auf Anfänger-Niveau mit Begriffen auf Experten-Niveau zu erklären. Die meisten Menschen, die nach Tutorials suchen, sind Anfänger.
- Sie sind vielleicht keine Anfänger im Programmieren, aber Anfänger in dem Bereich, den sie lernen möchten
Schreibe für Anfänger und vermeide möglichst Fachbegriffe auf Experten-Niveau
Vermeide schwierige Begriffe und schreibe in einfacher Sprache, die Leser verstehen können
In einem React-Tutorial sollte man zum Beispiel statt "JSX transpilation" eher etwas wie "eine einfache Webseite mit React erstellen" schreiben

Einen Titel formulieren, der ein klares Ergebnis verspricht

Der Titel sollte konkret vermitteln, was Leser durch das Tutorial lernen können
Vermeide unklare oder vage Titel und beschreibe das erwartete Ergebnis eindeutig
- Beispiel: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Das Ziel in der Einleitung erklären

Wenn Leser auf ein Tutorial klicken, interessieren sie sich bereits für das, was du sagst. Trotzdem musst du sie davon überzeugen, weiterzulesen
Leser stellen sich dabei zwei Fragen
- Sollte ich mich für diese Technologie interessieren?
- Und wenn ja: Ist dieses Tutorial das Richtige für mich?
Erkläre in der Einleitung knapp, warum die Technologie wichtig ist und warum das Tutorial nützlich ist
Gib nützliche Informationen, die Interesse wecken, und vermeide vage Formulierungen
- Beispiel: Ein Docker-Tutorial sollte klar erklären, welches Problem Docker löst und welches Ergebnis zu erwarten ist

Das Endergebnis vorab zeigen

Zeige so früh wie möglich eine Demo oder einen Screenshot dessen, was Leser mit dem Tutorial erstellen werden
- Wenn das Endergebnis früh gezeigt wird, ist das Ziel klarer
Zum Beispiel ein Screenshot des fertigen Produkts, der UI oder ein Beispiel der Funktionsweise

Code-Snippets schreiben, die per Copy-and-paste nutzbar sind

Schreibe so, dass Leser den Code leicht kopieren, in Editor oder Terminal einfügen und ausführen können
Entferne unnötige Elemente wie das Terminal-Promptzeichen $
Vereinfache Befehle mit nicht-interaktiven Flags und verwende &&, damit bei einem Fehler abgebrochen wird

In Befehlen lange Flags verwenden

Verwende in Befehlen statt kurzer Flags besser aussagekräftige lange Flags, damit auch Anfänger sie leicht verstehen
- Statt -r besser --recursive

Benutzerdefinierte Werte und wiederverwendbare Logik trennen

Trenne im Code klar zwischen Werten, die Benutzer ändern sollen, und Code, den sie nicht ändern sollten
Definiere benutzerdefinierte Werte über Umgebungsvariablen und verbessere so die Lesbarkeit des Codes

Den Aufwand für Leser reduzieren

Respektiere die Zeit der Leser, damit sie das Tutorial gern nutzen
Ersetze langweilige Aufgaben durch Befehls-Snippets
- Beispiel: Statt Dateien manuell zu bearbeiten, das Problem per Befehl lösen

So schreiben, dass der Code jederzeit funktionsfähig bleibt

Beispielcode sollte immer ausführbar sein und auch in Zwischenschritten funktionsfähig bleiben
Fehlerhafter oder nicht funktionierender Beispielcode verwirrt Leser

Nur ein Thema vermitteln

Ein Tutorial sollte sich auf ein einzelnes Thema konzentrieren und keine irrelevanten Technologien mischen
Ein Tutorial zur Suchfunktion sollte zum Beispiel nicht unnötig AI-Technologien hinzufügen

Klarheit vor Dekoration

Leser interessiert es nicht, ob eine Spielzeuganwendung schön aussieht
Reduziere unnötiges CSS oder Design-Elemente auf ein Minimum und konzentriere dich auf das Kernkonzept
Vermittle Konzepte mit einfachem Code statt mit unnötig komplexen Beispielen

Abhängigkeiten minimieren

Halte die Zahl der Abhängigkeiten, die Leser installieren müssen, möglichst klein, damit das Tutorial zugänglicher wird
Gib notwendige Abhängigkeiten klar an und nenne konkrete Versionen

Dateinamen eindeutig angeben

Weise Leser genau darauf hin, welche Dateipfade und Inhalte sie ändern müssen
Statt zum Beispiel "Einstellungen zur config-Datei hinzufügen" sollte der vollständige Dateipfad und genauer Code angegeben werden, einschließlich der exakten Zeile, die bearbeitet werden muss

Konsistente und beschreibende Überschriften verwenden

Verwende strukturierte Überschriften, damit Leser das Tutorial leicht überfliegen können
Gliedere das Tutorial mit Überschriften und formuliere sie so, dass sie die logische Struktur widerspiegeln
Halte Format, Perspektive und Zeitform der Überschriften konsistent

Belegen, dass die Lösung funktioniert

Wenn ein Tutorial die Installation eines Tools oder die Integration mehrerer Komponenten erklärt, zeige auch, wie das Ergebnis verwendet wird
- Zeige Lesern visuell das funktionierende Ergebnis des installierten oder integrierten Tools
Zeige zum Beispiel die erfolgreiche nginx-Seite und erkläre, wie man sie über die URL überprüft

Ein vollständiges Beispiel verlinken

Verlinke ein Repository mit dem gesamten Code des Tutorials, damit der komplette Ablauf nachvollzogen werden kann
Teile den Code jedes Schritts in separate git-Branches auf, damit Leser jeden Schritt nachvollziehen können

11 Kommentare

godogi7 2025-02-12

Als Referenz

wedding 2025-01-16

So was ist ein Lesezeichen wert!

ilikeall 2025-01-16

Ein guter Artikel.

halfenif 2025-01-16

Ich habe kürzlich das Tutorial von dagster ausprobiert und dachte mir, dass es wirklich gut gemacht ist.

https://courses.dagster.io/

aer0700 2025-01-16

Ich habe mir das Dagster-Tutorial komplett angesehen, und es ist wirklich sehr gut.
Das Django-Tutorial ist inhaltlich zwar gehaltvoll, aber mir persönlich ist es zu lang, deshalb mag ich es nicht so sehr. Ich wünschte, es wäre etwas stärker aufgeteilt.

savvykang 2025-01-16

Ein Beispiel für ein gut gemachtes Tutorial gibt es auch bei Django: https://docs.djangoproject.com/en/5.1/intro/tutorial01/

jhj0517 2025-01-16

Einfache Sprache verwenden & das Endergebnis zuerst zeigen.

aer0700 2025-01-15

Statt die langweilige grundlegende Verwendung eines Frameworks zu zeigen, gibt es oft Tutorial-Dokumente, die lieber zeigen wollen, wie cool dieses Framework ist.
Wenn ich auf „Get started“ klicke und dort als Tutorial für die grundlegende Verwendung ein 10-seitiges Dokument steht, finde ich das furchtbar.

beenzinozino 2025-01-16

Alle sind ja unglaublich...

savvykang 2025-01-15

https://tanstack.com/table/latest/docs/introduction

nono9633 2025-01-15

https://github.com/tmux/tmux/wiki/Getting-Started