はじめに
Codelab は、マークダウン構文で記述されたインタラクティブなチュートリアルです。Codelab は blocklycodelabs.dev で公開されています。Codelab では、自然言語、コードサンプル、スクリーンショットを組み合わせて、より興味深いチュートリアルを作成できるようになっています。Codelab の対象ユーザーは、読みながらコードを実行しながら実行します。
Codelab を書くことは、コミュニティに貢献する優れた方法です。知識を共有し、同じ問題に直面する次のデベロッパーの作業を効率化できます。
優れた Codelab とは
優れた Codelab は、焦点を絞った、わかりやすいものです。ビルドの内容と学習する内容をユーザーに明確に示し、特定のタスクを完了するためのコードの作成と理解を順を追って行います。
プロセス
Codelab に関するアイデアをお持ちの場合は、blockly-samples リポジトリで機能リクエストを使用してお知らせください。Codelab で教える内容と作成する内容の説明を含めます。検討したうえで、アイデアを改善します。 その後、コードを作成して、pull リクエストを送信できます。審査が完了すると、Blockly チームのメンバーが公開します。
文章を書くヒント
このページの残りの部分では、Codelab の記述に役立つヒントと質問を紹介します。
テクニカル ライティングの概要については、テクニカル ライティング ワンをご覧ください。
対象
- どのような読者をターゲットとしていますか？
- Blockly の使用についてすでに知っていることは何か？
- 視聴者は何を学びたいのか、
設定
- ユーザーがコードを実行するために最低限必要な設定は？
必要に応じて、スターター コードと完成したコードを examples ディレクトリに公開できます。
構造
他の文章と同様に、まずは概要から始めます。これは、ほとんどの Codelab に適した構造です。
- 概要
- 学習内容
- 作成するアプリの概要
- 知っておくべきポイント
- 設定手順
- ステップ 1: [ここにタイトルを入力]
- 説明/動機
- コードサンプル
- 期待される結果
- （省略可）詳細
- ...
- ステップ 10: [ここにタイトルを入力]
- 概要
- 学習した内容
- 作成したもの
- 補足資料
- 完成したコードへのリンク（ある場合）
ステップは 10 以上にすることもできますが、20 ステップに達した場合は、2 つの Codelab に分割することを検討してください。
文章のスタイル
- 会話調の文章スタイルを使用する。
- 見出しを使って組織を明確にします。
- 箇条書きを使用して文章を分割する。
- 画像や GIF を使用します。
コードスタイル
- ES5、ES6、TypeScript のいずれでも記述できますが、どちらが最初に記述されているかを読者に伝えます。
- Google スタイルガイドに準拠