Einführung
Ein Codelab ist ein interaktives Tutorial, das in Markdown-Syntax geschrieben ist. Unsere Codelabs werden unter blocklycodelabs.dev veröffentlicht. Codelabs nutzen eine Mischung aus natürlicher Sprache, Codebeispiele und Screenshots, um ein interessanteres Tutorial zu schaffen. Die Zielnutzer eines Codelabs folgen den Code und führen ihn beim Lesen aus.
Das Schreiben eines Codelabs ist eine großartige Möglichkeit, zur Community beizutragen. Es ist eine Möglichkeit, Ihr Wissen zu teilen und dem nächsten Entwickler, der auf das gleiche Problem stößt, das Leben zu erleichtern.
Was macht ein gutes Codelab aus?
Ein gutes Codelab ist fokussiert und gut lesbar. Sie teilt dem Nutzer klar mit, was er erstellen wird und was er lernen wird. Außerdem wird er durch das Schreiben und Verstehen von Code geführt, um eine bestimmte Aufgabe auszuführen.
Prozesse
Wenn Sie eine Idee zu einem Codelab haben, können Sie uns diese über eine Funktionsanfrage im Repository „blockly-sample“ mitteilen. Geben Sie an, was Sie alles unterrichten möchten und was Sie in dem Codelab erstellen werden. Wir werden die Idee besprechen und präzisieren. Diese können Sie sich dann notieren und eine Pull-Anfrage senden. Sobald die Überprüfung abgeschlossen ist, wird sie von einem Mitglied des Blockly-Teams veröffentlicht.
Schreibtipps
Auf der folgenden Seite finden Sie einige Tipps und Fragen, die Ihnen beim Schreiben eines Codelabs helfen.
Unter Technical Writing One finden Sie eine kurze Einführung in das technische Schreiben.
Zielgruppe
- Wer ist die Zielgruppe?
- Was wissen sie schon über die Verwendung von Blockly?
- Was möchten sie lernen?
Einrichtung
- Wie muss der Nutzer mindestens eingerichtet werden, damit er Ihren Code ausführen kann?
Bei Bedarf können Sie Startcode und abgeschlossenen Code im Verzeichnis examples veröffentlichen.
Struktur
Beginnen Sie wie bei jedem Text mit einer Gliederung. Diese Struktur eignet sich für die meisten Codelabs:
- Einführung
- Lerninhalte
- Aufgaben
- Wissenswertes
- Einrichtungsanleitung
- Schritt 1: [Titel einfügen]
- Erklärung/Motivation
- Codebeispiel
- Erwartete Ergebnisse
- (Optional) Weitere Erläuterungen
- ...
- Schritt 10: [Titel einfügen]
- Zusammenfassung
- Das haben Sie gelernt
- Was Sie erstellt haben
- Weitere Ressourcen
- Link zum fertigen Code (falls verfügbar)
Sie können zwar mehr als zehn Schritte ausführen, aber wenn Sie 20 erreichen, empfiehlt es sich, sie in zwei Codelabs aufzuteilen.
Schreibstil
- Verwenden Sie einen dialogorientierten Schreibstil.
- Verwenden Sie Überschriften, um die Organisation deutlich zu machen.
- Verwenden Sie Listen mit Aufzählungszeichen, um unendliche Textpassagen zu trennen.
- Verwenden Sie Bilder und GIFs!
Codestil
- Sie können in ES5, ES6 oder TypeScript schreiben, aber dem Leser mitteilen, worum es am Anfang geht.
- Folgen Sie dem Google Style Guide.