チュートリアルは、ユーザーが製品について学習し、タスクを完了するためにワークフロー全体を通してガイドすることで、現実世界の問題を解決するのに役立ちます。 チュートリアルは、他のコンテンツよりも会話的なトーンです。 チュートリアルは、さまざまな技術的知識を持つ閲覧者がアクセスできる状態を維持したまま、開発者同士が会話するようなものです。 チュートリアルがある製品には、既にクイックスタートが含まれている必要があります。 小さなワークフローの場合は、代わりにクイックスタート モデルを使用してください。
チュートリアルは、専門家のアドバイスと、問題に関連するベスト プラクティスの詳細な説明が必要なユーザー向けです。 また、チュートリアルは、他の製品で過去に同様の解決策を実装したユーザーが GitHub を使用する場合にも役立ちます。 チュートリアルは、ユーザーが解決策がニーズに適しているかどうかを検証するのにも役立つ場合があります。
サイト全体でチュートリアルとクイックスタートをまとめて "ガイド" と言います。 /guides ランディング ページでは、ドキュメント セットのガイドのリストにチュートリアル、クイックスタート、特定の手続き型記事が含まれています。
チュートリアルの記述方法
チュートリアル テンプレートについては、「テンプレート」を参照してください。
チュートリアルのコンテンツ:
- はじめに
- 対象ユーザーを明確にします。
- 前提条件と必要な事前知識を明確に示します。
- 誰かが達成または構築するものを示します。
- 成功したプロジェクトの例が含まれます。
- ユーザーがタスクを完了するのに要する可能性がある予期された時間は含まれません。これは、チュートリアルを完了するユーザーの経験レベルによって異なります。
- 手続き型セクション
- チュートリアルの対象ユーザーに基づいて、手順は手続き型コンテンツで使用されるものよりも明示的で正式ではない可能性があります。 対象ユーザーがその詳細レベルを必要としない場合は、既存の再利用可能なものを使用してこれらの手順を形成する必要はありません。
- 使用する: "プロファイルから、 [設定] をクリックし、次に [開発者向け設定] をクリックします。"
- 避ける: 任意のページで、右上隅にあるプロファイルの画像をクリックし、次に [設定] をクリックします。 左側のサイドバーで、 [開発者向け設定] をクリックします。
- チュートリアルの情報の流れを妨げないように、他の記事やリソースをレプリケートするのではなく、それらにリンクします。
- 視覚的な手掛かりを示します。コード ブロックとスクリーンショットを頻繁に使用すると、ユーザーに正しいアクションを実行していると安心させるのに役立ちます。
- 実際の例を提供します。
- たとえば、"コミット メッセージを入力する" ように指示しないでください。代わりに、前の手順に一致する適切なコミット メッセージの例を示します。
- チュートリアルの対象ユーザーに基づいて、手順は手続き型コンテンツで使用されるものよりも明示的で正式ではない可能性があります。 対象ユーザーがその詳細レベルを必要としない場合は、既存の再利用可能なものを使用してこれらの手順を形成する必要はありません。
- トラブルシューティング
- タスクで何が問題になる可能性があるかを確認し、閲覧者が直面する可能性のあるいくつかの一般的な問題をその解決策と共に一覧表示します。
- まとめ
- 達成または構築された内容を確認します。 成功したプロジェクトの例として、概要に示されているプロジェクトに戻って参照します。
- 次の手順
- チュートリアルを完了した後に他のユーザーが実行できる 2 から 3 つのアクション可能な次の手順を含めます。 次のような他の関連情報にリンクします。
- 導入された概念を示す GitHub のプロジェクト
- docs.github.com の関連情報
- 関連する GitHub Skills
- 関連する公開された講演、ブログ投稿、または Hubber によるコミュニティ フォーラム シリーズの投稿
- チュートリアルを完了した後に他のユーザーが実行できる 2 から 3 つのアクション可能な次の手順を含めます。 次のような他の関連情報にリンクします。
チュートリアルのタイトル ガイドライン
- 手続き型記事のタイトル ガイドラインに従ってください。
- タイトルに "チュートリアル" や "ガイド" を使用しないでください。
チュートリアルの例
チュートリアル:
言語とフレームワークのガイド: