Codelab erstellen

Einführung

Ein Codelab ist ein interaktives Tutorial, das in Markdown-Syntax geschrieben wurde. Wir veröffentlichen unsere Codelabs unter blocklycodelabs.dev. In Codelabs werden natürliche Sprache, Codebeispiele und Screenshots kombiniert, um ein interessanteres Tutorial zu erstellen. Der Zielnutzer eines Codelabs folgt den Anweisungen und führt den Code aus, während er liest.

Ein Codelab zu schreiben ist eine gute Möglichkeit, zur Community beizutragen. So können Sie Ihr Wissen weitergeben und das Leben des nächsten Entwicklers erleichtern, der auf dasselbe Problem stößt.

Was macht ein gutes Codelab aus?

Ein guter Codelab ist fokussiert und lesbar. Darin wird dem Nutzer klar gesagt, was er erstellen und lernen wird. Außerdem wird er durch das Schreiben und Verstehen von Code geführt, um eine bestimmte Aufgabe zu erledigen.

Prozess

Wenn Sie eine Idee für ein Codelab haben, können Sie uns dies mitteilen, indem Sie im Repository „blockly-samples“ einen Funktionsvorschlag einreichen. Beschreiben Sie, was Sie vermitteln möchten und was im Codelab erstellt wird. Wir besprechen und verfeinern die Idee. Anschließend können Sie den Artikel verfassen und eine Pull-Anfrage dafür senden. 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 Schreiben eines Codelabs helfen sollen.

Technical Writing One bietet 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 lernen?

Einrichtung

• Welche Mindesteinrichtung ist erforderlich, damit der Nutzer Ihren Code ausführen kann?

Bei Bedarf können Sie Startercode und fertigen Code im Verzeichnis examples veröffentlichen.

Struktur

Wie bei jedem Text sollten Sie mit einer Gliederung beginnen. Das ist eine gute Struktur für die meisten Codelabs:

• Einführung
  • Lerninhalte
  • Aufgaben
  • Was Sie wissen sollten
  • Anleitung zur Einrichtung
• Schritt 1: [Titel]
  • Erklärung/Motivation
  • Codebeispiel
  • Erwartete Ergebnisse
  • (Optional) Weitere Erläuterungen
• …
• Schritt 10: [Titel hier einfügen]
• Zusammenfassung
  • Das haben Sie gelernt
  • Was Sie erstellt haben
  • Zusätzliche Ressourcen
  • Link zum vollständigen Code (falls verfügbar)

Sie können zwar mehr als zehn Schritte haben, aber wenn Sie zwanzig erreichen, sollten Sie das Codelab in zwei Codelabs aufteilen.

Schreibstil

• Verwenden Sie einen ungezwungenen Schreibstil.
• Verwenden Sie Überschriften, um die Organisation zu verdeutlichen.
• Verwenden Sie Aufzählungslisten, um Textblöcke aufzulockern.
• Bilder und GIFs verwenden

Codestil

• Sie können in ES5, ES6 oder TypeScript schreiben, sollten dem Leser aber am Anfang mitteilen, welche Sprache Sie verwenden.
• Google-Styleguide