はじめに
Codelab は、Markdown 構文で記述されたインタラクティブなチュートリアルです。Codelab は blocklycodelabs.dev で公開されています。Codelab では、自然言語、コードサンプル、スクリーンショットを組み合わせて、より興味深いチュートリアル エクスペリエンスを実現しています。Codelab の対象ユーザーは、コードを読みながら、そのコードを実行します。
Codelab を作成することは、コミュニティに貢献する優れた方法です。これは、知識を共有し、同じ問題に直面した次のデベロッパーの負担を軽減する方法です。
優れた Codelab とは
優れた Codelab は、焦点を絞り、読みやすくします。作成する内容と学習内容を明確に示し、特定のタスクを完了するためにコードの作成と理解を段階的に説明します。
プロセス
Codelab のアイデアがある場合は、blockly-samples リポジトリで機能リクエストを送信してご連絡ください。教えたい内容と、Codelab で作成する内容の説明を記載します。アイデアについて話し合い、改善します。その後、それを記述してpull リクエストを送信できます。審査が完了すると、Blockly チームのメンバーが公開します。
文章を書くヒント
このページの残りの部分では、Codelab の作成に関するヒントと質問について説明します。
テクニカル ライティングの概要については、テクニカル ライティング 1 をご覧ください。
オーディエンス
- 対象読者は誰ですか？
- 生徒は Blockly の使用についてすでに何を知っていますか？
- ユーザーが学習しようとしていること
セットアップ
- ユーザーがコードを実行するために必要な最小限の設定は何ですか？
必要に応じて、examples ディレクトリにスターター コードと完成したコードを公開できます。
構造
他の文章と同様に、アウトラインから始めます。これは、ほとんどの Codelab に適した構造です。
- はじめに
- 学習内容
- 作成するアプリの概要
- ご注意いただきたい点
- 設定の手順
- ステップ 1: [タイトルをここに入力]
- 説明/動機
- コードサンプル
- 期待される結果
- （省略可）詳細な説明
- ...
- ステップ 10: [タイトルをここに入力]
- 概要
- 学習した内容
- 作成した内容
- 参考情報
- 完成したコードへのリンク（ある場合）
ステップは 10 ステップを超えても構いませんが、20 ステップを超える場合は、2 つの Codelab に分割することを検討してください。
文章のスタイル
- 会話的な文体を使用します。
- 見出しを使用して、構成を明確にします。
- 箇条書きを使用して、長い文章を分割します。
- 画像や GIF を使用しましょう。
コードスタイル
- ES5、ES6、TypeScript のいずれかで記述できますが、最初にどの言語で記述しているかを読み手に伝えてください。
- Google スタイルガイドに沿って作成します。