Tutorials helfen Menschen dabei, Produkte kennenzulernen und reale Probleme zu beheben, indem sie durch den gesamten Workflow geleitet werden, um eine Aufgabe abzuschließen. Tutorials sind konversationsbezogener als andere Inhalte. Ein Tutorial ähnelt einer Entwickler-zu-Entwickler-Konversation, bleibt dabei aber für Leser*innen mit unterschiedlichen technischen Kenntnissen zugänglich. Produkte mit Tutorials müssen bereits eine Schnellstartanleitung umfassen. Verwenden Sie für Workflows mit Bitgröße stattdessen das Schnellstartanleitungsmodell.
Tutorials richten sich an Personen, die kompetente Beratung und eine detaillierte Erläuterung bewährter Methoden im Zusammenhang mit ihrem Problem benötigen. Tutorials helfen auch Personen, die in der Vergangenheit ähnliche Lösungen mit anderen Produkten implementiert haben, bei der Verwendung von GitHub. Tutorials können auch dabei helfen, zu überprüfen, ob die Lösung für ihre Anforderungen geeignet ist.
Wir bezeichnen Tutorials und Schnellstartanleitungen auf der gesamten Website als „Anleitungen“. Auf /guides-Startseiten stellen wir Tutorials, Schnellstartanleitungen und bestimmte prozedurale Artikel in der Liste der Anleitungen für eine Dokumentationsgruppe bereit.
Schreiben eines Tutorials
Die Tutorialvorlage findest du unter Vorlagen.
Inhalte von Tutorials:
- Einführung
- Die Zielgruppe wird genannt.
- Die Voraussetzungen und erforderlichen Vorkenntnisse werden deutlich genannt.
- Es wird erläutert, was erreicht oder erstellt wird.
- Es ist ein Beispiel für ein erfolgreiches Projekt enthalten.
- Die benötigte Zeit zum Abschließen der Aufgabe wird nicht angegeben. Dies hängt von der Erfahrung der Person ab, die das Tutorial abschließt.
- Prozedurale Abschnitte
- Basierend auf der Zielgruppe des Tutorials können die Schritte weniger explizit und formal sein als diejenigen, die in prozeduralen Inhalten verwendet werden. Du musst keine vorhandenen wiederverwendbaren Elemente verwenden, um diese Schritte zu erstellen, wenn die Zielgruppe diese Detailebene nicht erfordert.
- Verwenden Sie Folgendes: „Klicken Sie in Ihrem Profil auf Einstellungen und dann auf Entwicklereinstellungen.“
- Vermeiden Sie die Verwendung von „Klicken Sie auf einer beliebigen Seite in der oberen rechten Ecke auf dein Profilfoto und anschließend auf Einstellungen.“. Klicken Sie in der linken Seitenleiste auf Entwicklereinstellungen.
- Erstelle Verknüpfungen zu anderen Artikeln oder Ressourcen, anstatt diese zu replizieren, um zu vermeiden, dass der Informationsfluss im Tutorial unterbrochen wird.
- Geben Sie visuelle Hinweise. Verwenden Sie Codeblöcke und Screenshots, sodass Personen wissen, dass sie die richtigen Aktionen ausführen.
- Geben Sie echte Beispiele an.
- Vermeiden Sie beispielsweise „Geben Sie eine Commitnachricht ein“. Stellen Sie stattdessen eine entsprechende Beispielcommitnachricht bereit, die den vorherigen Schritten entspricht.
- Basierend auf der Zielgruppe des Tutorials können die Schritte weniger explizit und formal sein als diejenigen, die in prozeduralen Inhalten verwendet werden. Du musst keine vorhandenen wiederverwendbaren Elemente verwenden, um diese Schritte zu erstellen, wenn die Zielgruppe diese Detailebene nicht erfordert.
- Problembehandlung
- Versuchen Sie zu erkennen, welches Problem bei der Aufgabe auftreten könnte, und liste einige häufige Probleme auf, die bei den Leser*innen bei Verwendung von Lösungen auftreten können.
- Zusammenfassung
- Überprüfen Sie, was erreicht oder erstellt wurde. Sehen Sie sich das in der Einführung angegebene Projekt als Beispiel für ein erfolgreiches Projekt an.
- Nächste Schritte
- Schließen Sie zwei bis drei handlungsrelevante nächste Schritte ein, die nach Abschluss des Tutorials ausgeführt werden können. Fügen Sie Links zu anderen zugehörigen Informationen wie den folgenden ein:
- Projekte auf GitHub zur Veranschaulichung der eingeführten Konzepte
- Relevante Informationen auf docs.github.com
- Relevante Kenntnisse im Zusammenhang mit GitHub Skills
- Relevante veröffentlichte Vorträge, Blogbeiträge oder Communityforumsbeiträge von Hubbers
- Schließen Sie zwei bis drei handlungsrelevante nächste Schritte ein, die nach Abschluss des Tutorials ausgeführt werden können. Fügen Sie Links zu anderen zugehörigen Informationen wie den folgenden ein:
Titelrichtlinien für Tutorials
- Befolge die Titelrichtlinien für prozedurale Artikel.
- Vermeiden Sie Wörter wie „Tutorial“ oder „Anleitung“ im Titel.
Beispiele für Tutorials
Tutorials:
- Hinzufügen von Bezeichnungen zu Issues
- Installieren eines Apple-Zertifikats auf macOS-Runnern für die Xcode-Entwicklung
Sprach- und Frameworkanleitungen: