Einführung
Ein Codelab ist eine interaktive Anleitung, die in Markdown-Syntax geschrieben wurde. Wir veröffentlichen unsere Codelabs unter blocklycodelabs.dev. Codelabs verwenden eine Mischung aus natürlicher Sprache, Codebeispielen und Screenshots, um die Anleitung interessanter zu gestalten. Die Zielgruppe eines Codelabs folgt der Anleitung und führt den Code aus, während sie liest.
Das Erstellen eines Codelabs ist eine gute Möglichkeit, zur Community beizutragen. So können Sie Ihr Wissen teilen und es dem nächsten Entwickler erleichtern, der auf dasselbe Problem stößt.
Was macht ein gutes Codelab aus?
Ein gutes Codelab ist fokussiert und gut lesbar. Es wird dem Nutzer klar und deutlich erklärt, was er erstellen und was er lernen wird. Außerdem wird er durch das Schreiben und Verstehen von Code für die Ausführung einer bestimmten Aufgabe geführt.
Prozess
Wenn Sie eine Idee für ein Codelab haben, können Sie uns dies mitteilen, indem Sie im Blockly-Samples-Repository einen Funktionsvorschlag einreichen. Geben Sie eine Beschreibung dessen an, was Sie vermitteln möchten und was Sie im Codelab erstellen werden. Wir besprechen und optimieren die Idee. Anschließend können Sie sie aufschreiben und einen Pull-Request dafür einreichen. Nach der Überprüfung wird sie von einem Mitglied des Blockly-Teams veröffentlicht.
Schreibtipps
Auf dem Rest dieser Seite finden Sie Tipps und Fragen, die Ihnen beim Erstellen eines Codelabs helfen sollen.
Technical Writing One ist eine kurze Einführung in das technische Schreiben.
Zielgruppe
- Wer ist die Zielgruppe?
- Was wissen sie bereits über die Verwendung von Blockly?
- Was möchten sie herausfinden?
Einrichtung
- Welche Mindesteinrichtung ist erforderlich, damit der Nutzer Ihren Code ausführen kann?
Falls hilfreich, können Sie Ausgangscode und fertigen Code im Verzeichnis examples veröffentlichen.
Struktur
Wie bei jedem Text beginnen Sie mit einer Gliederung. Das ist eine gute Struktur für die meisten Codelabs:
- Einführung
- Lerninhalte
- Aufgaben
- Was Sie wissen sollten
- Anleitung zur Einrichtung
- Schritt 1: [Titel hier einfügen]
- Erklärung/Begründung
- Codebeispiel
- Erwartete Ergebnisse
- (Optional) Weitere Erläuterung
- …
- Schritt 10: [Title goes here]
- Zusammenfassung
- Das haben Sie gelernt
- Ihre Kreationen
- Zusätzliche Ressourcen
- Link zum fertigen Code (falls verfügbar)
Sie können auch mehr als zehn Schritte haben, aber wenn Sie zwanzig erreichen, sollten Sie die Anleitung in zwei Codelabs aufteilen.
Schreibstil
- Verwenden Sie einen ungezwungenen Schreibstil.
- Verwenden Sie Überschriften, um die Struktur klar zu machen.
- Verwenden Sie Aufzählungslisten, um Textblöcke aufzulockern.
- Verwenden Sie Bilder und GIFs.
Codestil
- Sie können in ES5, ES6 oder TypeScript schreiben, müssen aber am Anfang angeben, um welche Sprache es sich handelt.
- Beachten Sie den Google-Stilguide.