Codelab を作成する

はじめに

Codelab は、Markdown 構文で記述されたインタラクティブなチュートリアルです。Codelab は blocklycodelabs.dev で公開しています。Codelab では、自然言語、コードサンプル、スクリーンショットを組み合わせて、より興味深いチュートリアル エクスペリエンスを実現しています。この Codelab の対象ユーザーは、読みながらコードを実行します。

Codelab を作成することは、コミュニティに貢献する優れた方法です。これは、知識を共有し、同じ問題に直面する次のデベロッパーの負担を軽減する方法です。

優れた Codelab とは

優れた Codelab は、焦点が絞られていて読みやすいものです。ユーザーが何を構築し、何を学ぶのかを明確に伝え、特定のタスクを完了するためのコードの作成と理解をユーザーに説明します。

プロセス

Codelab のアイデアがある場合は、blockly-samples リポジトリで機能リクエストを作成して、お知らせください。教えたいことと、コードラボで作成するものを説明します。アイデアについて話し合い、洗練させます。その後、それを記述して、pull リクエストを送信できます。審査が完了すると、Blockly チームのメンバーが公開します。

文章を書くヒント

このページの残りの部分は、Codelab の作成をガイドするヒントと質問のセットです。

テクニカル ライティングの概要については、テクニカル ライティング 1 をご覧ください。

オーディエンス

  • 対象読者は誰ですか？
  • Blockly の使用について、生徒はすでにどのようなことを知っていますか？
  • 何を学ぼうとしているか。

セットアップ

  • ユーザーがコードを実行するために必要な最小限のセットアップは何ですか？

必要に応じて、examples ディレクトリにスターター コードと完成したコードを公開できます。

構造

他の文章と同様に、まずアウトラインを作成します。ほとんどの Codelab に適した構造は次のとおりです。

  • はじめに
    • 学習内容
    • 作成するアプリの概要
    • ご注意いただきたい点
    • 設定の手順
  • ステップ 1: [タイトルをここに入力]
    • 説明/動機
    • コードサンプル
    • 期待される結果
    • （省略可）詳細な説明
  • ...
  • ステップ 10: [タイトルをここに配置]
  • 概要
    • 学習した内容
    • 構築した内容
    • 参考情報
    • 完成したコードへのリンク（該当する場合）

10 個以上のステップを設定できますが、20 個に達する場合は、2 つの Codelab に分割することを検討してください。

文章のスタイル

  • 会話形式の文体を使用します。
  • 見出しを使用して、構成を明確にする。
  • 箇条書きを使用して、テキストの壁を分割します。
  • 画像や GIF を使用する

コードのスタイル