tutorial-design

チュートリアルの設計

複雑な技術概念を、演習、チェックポイント、トラブルシューティングのガイダンスを含む、魅力的で段階的な学習体験へと変える、実践的なチュートリアルを設計して作成します。

このスキルを使用する場面

• ライブラリ、API、ツールの入門チュートリアルを作成する
• チーム研修やカンファレンスのワークショップ資料を作成する
• 難易度が段階的に上がる複数パートの学習シリーズを構築する
• 自己評価用チェックポイントを含むコーディング演習を設計する
• 既存のドキュメントをガイド付きの学習コンテンツに変換する
• ユーザーがすぐに作業を始められるクイックスタートガイドを作成する

クイックリファレンス

リソース	目的	読み込むタイミング
references/design-patterns.md	段階的な情報開示のパターン、演習の種類、チェックポイントの設計、難易度の調整、前提知識の整理	チュートリアルの構成を計画するとき、または演習を設計するとき

---

ワークフローの概要

Phase 1: Objectives   → Define learning outcomes, prerequisites, and audience
Phase 2: Decompose    → Break concepts into atomic, sequenced steps
Phase 3: Design       → Create exercises, checkpoints, and troubleshooting tips
Phase 4: Write        → Produce tutorial content with runnable examples
Phase 5: Validate     → Test the tutorial path end-to-end

---

フェーズ 1：学習目標を定義する

すべてのチュートリアルは、明確な成果目標から始まります。

冒頭セクションのテンプレート

## What You'll Learn

- [Specific, measurable outcome 1]
- [Specific, measurable outcome 2]
- [Specific, measurable outcome 3]

## Prerequisites

- [Required knowledge or setup]
- [Tools needed]

## Time Estimate

~[X] minutes

## What You'll Build

[Brief description or screenshot of the final result]

効果的な目標の書き方：

• 行動を表す動詞を使います。「理解する」や「学ぶ」ではなく、「構築する」「設定する」「デバッグする」「デプロイする」などを使います
• 検証可能な内容にします。読者が各成果を達成したかどうか確認できるようにします
• 範囲を現実的に設定します。チュートリアルごとに目標は 3～5 個にします

---

フェーズ 2：概念を分解する

トピックを、個別の学習ステップに分解します。

順序付けのルール

1. セクションごとに概念は 1 つ — 新しいアイデアを一度に 2 つ導入しないでください
2. 依存関係に沿った順序 — 概念は、それまでに学んだ内容を基礎として積み上げる必要があります
3. 抽象より具体を先に — 動作する例を示してから、理論を説明します
4. 複雑なものよりシンプルなものを先に — 最小限のバージョンから始め、段階的に複雑さを加えます

概念マップ

執筆する前に、依存関係を示すグラフを作成します。

[Prerequisites] → [Core concept A] → [Core concept B]
                                    ↘ [Variation 1]
                  [Core concept A] → [Core concept C] → [Advanced topic]

各ノードがセクションになります。依存関係に基づいてセクションの順序を決めます。

---

フェーズ 3：演習とチェックポイントを設計する

演習の種類

種類	難易度	使用する場面
穴埋め問題	低	例を見た後に構文を定着させる
デバッグ課題	中	エラーの読み取り方やよくある間違いを教える
拡張課題	中	動作するコードに機能を追加する
ゼロから作成	高	要件だけを基に構築する
リファクタリング	高	既存の実装を改善する

チェックポイントのパターン

主要なセクションの後には、必ずチェックポイントを挿入します。

### Checkpoint

At this point you should have:
- [ ] A running server on port 3000
- [ ] The `/health` endpoint returning `{ "status": "ok" }`
- [ ] Server logs showing incoming requests

**If something's wrong**, see the [Troubleshooting](#troubleshooting) section below.

トラブルシューティングのセクション

各セクションについて、よくあるエラーを 2～3 個想定します。

### Troubleshooting

**Error: `EADDRINUSE: address already in use`**
Another process is using port 3000. Run `lsof -i :3000` to find it,
then stop it or change your port.

**Error: `Cannot find module 'express'`**
You haven't installed dependencies yet. Run `npm install` in the project root.

---

フェーズ 4：チュートリアルを執筆する

セクションの構成（各概念について）

1. 簡単な導入（1～2 文） — このセクションで扱う内容と、その重要性を説明します
2. 最小限の例 — 概念を示す、完全で実行可能なコードを用意します
3. 行ごとの説明 — 重要な部分を順に説明します
4. 試してみる — コードを実行するよう読者に促し、期待される結果を伝えます
5. 拡張する — 理解を深めるための任意の演習を用意します
6. トラブルシューティング — このセクションでよくあるエラーを説明します

執筆の原則

• まず見せてから説明する — 先にコードを示し、その後に理論を説明します
• こまめに検証する — 読者が 2～3 分ごとにコードを実行できるようにします
• 失敗を次につなげる — デバッグを教えるため、意図的なエラーを含めます
• 複雑さを段階的に増やす — 各ステップでは、前のステップに 1 つの要素を追加します
• コピー＆ペーストしやすくする — 例はそのまま貼り付けて動作するようにします

コンテンツの要素

コードブロックの要件：

• 完全で実行可能であること（重要な処理を ... で省略しない）
• 期待される出力を別のブロックに含めること
• 意味の分かりやすい変数名を使うこと
• 自明でない部分に限ってインラインコメントを付けること

説明の要件：

• 実際のユースケースと関連付けること
• 各ステップの「理由」を説明すること
• 身近な概念にたとえること
• 読者の「でも、これはどうなるのか？」という疑問を先回りして取り上げること

締めくくりのセクション

## Summary

You've learned how to:
- [Outcome 1 restated]
- [Outcome 2 restated]

## Next Steps

- [Natural follow-on tutorial or topic]
- [Related documentation]
- [Community resources]

---

フェーズ 5：検証

公開する前に、チュートリアルの全工程をテストします。

1. クリーンな環境からすべての手順を実行します
2. すべてのコード例を実行し、出力が一致することを確認します
3. トラブルシューティングの各シナリオを少なくとも一度は試します
4. チュートリアルにかかる時間を計測します。見積もりどおりでしょうか？
5. このトピックに詳しくない人に試してもらいます

---

チュートリアルの形式

形式	所要時間	使用する場面
クイックスタート	5 分	初めて使う場合、すぐに動かしたい場合
徹底解説	30～60 分	単一のトピックを包括的に掘り下げる場合
ワークショップシリーズ	複数パート	複数のセッションを通じて段階的に学ぶ場合
クックブック	可変	課題と解決策の組み合わせを、順不同で読む場合
インタラクティブな演習	15～45 分	ガイド付きの手順を備えた実践環境を使う場合

アンチパターン

• 必要になる前に概念を紹介する（「後で使います」）
• 単独で実行できないコードスニペットを示す
• 前提条件に記載されていない知識を前提とする
• コードを挟まず、長文を続ける
• 解答のない演習（折りたたみ表示や非表示のものも含む）
• 「なぜ」を省略し、「どうやるか」だけを示す