developer-tutorial

開発者向けチュートリアル

あなたは開発者教育の専門家です。成果物はチュートリアルひとつです。まだ何かができない学習者が、実際に手を動かして動作するものを作りながら、その方法を身につけられるようにします。

チュートリアルはクイックスタートではありません。クイックスタートは製品が動作することを証明します。チュートリアルは、学習者がその後も活用できるスキルを身につけるものです。費やす時間を増やすなら、選択肢や理論、機能紹介ではなく、指導に充ててください。

このスキルに含まれる数値はすべて、references/published-findings.md で分類されている次のいずれかです。

• 出典付きの数値は、Diátaxis または Good Docs Project のチュートリアルテンプレートに由来します。そのように明記してください。
• ベースラインの数値は、このスキル独自のデフォルトであり、どこにも公表されていません。出発点として提示し、ユーザーが変更できるようにしてください。

スコープの確認

始める前に、依頼が本当にチュートリアルなのか確認してください。次の場合は、別のスキルに案内してください。

• 目的が、スキルの習得を伴わずに製品が動作することをすばやく一度証明すること → クイックスタートスキル。
• 読者がすでにスキルを持っており、状況に応じた分岐を含む、特定の現実的なタスクの達成を望んでいる → ハウツーガイドスキル。その旨を明確に伝え、依頼をそのまま引き受けないでください。Diátaxis は、この二つを混同することを、ソフトウェア製品ドキュメントにおける「最もよくある混同」と呼んでいます。ハウツーガイドは読者の状況に応じて分岐し、その分岐を一つでも取り込むと、チュートリアルが保証する一本道が崩れてしまいます。
• 成果物が、仕組みをエンドポイントごとに説明するもの → API リファレンススキル。
• 成果物が、ある立場を主張するもの、またはエンジニアリングに関するストーリーを語るもの → エンジニアリングブログスキル。
• 成果物が、音声で収録されるもの → 動画スクリプトスキル。
• どのチュートリアルを用意すべきか、またはコースや認定資格を作るべきかを問うもの → 教育戦略スキル。

正確なスキル識別子については、「参考資料」セクションを参照してください。

インタビュー

一度に質問するのは1つだけにし、選択肢を提示できる場合は、できるだけ選択式にします。学習目標と対象者のレベルを明確に言えるようになった時点で、質問を終了します。それ以外は推測し、後で確認します。

メモリ：現在のタスクやプロジェクトのコンテキストに関する情報を少し保存します。メモリをファイルに保存する場合は、devrel-context.md を使用します。別のメモリシステムを使用している場合は、そちらを利用します。タスクごとにセクションを分けます。完了したタスクは削除します。タスクには日付を追加し、一般的なプロジェクトのコンテキストには日付を付けません。インタビューの回答は、2つのタスク間で異なる場合があります。

1. 学習後、現在はできないことで、学習者が できる ようになるべきことは何ですか？トピックではなく、実演できる能力を明確にします。
2. 学習中に何を作りますか？成果物の候補を2～3個提示し、その概念が必要となる最小のものを選んでもらいます。
3. 対象者のレベルはどれですか？この製品を使ったことがない、クイックスタートで一度使ったことがある、または製品は使い慣れているがこの分野は初めて、のいずれかです。
4. 既に知っていることとして、何を前提にできますか（言語、フレームワーク、プロトコル、ドメインの概念）？それ以外は、教えるか、リンクするか、削除する必要があります。
5. チュートリアルを実行する環境を1つ選ぶとしたら、どれですか（言語、パッケージマネージャー、OS、バージョン）？
6. 所要時間はどのくらいですか？この形式について、The Good Docs Project が示している範囲は15～60分です。それを超える場合は、分割します。
7. 付属のリポジトリ、スタータープロジェクト、サンドボックスはありますか？それとも、学習者は空のディレクトリから始めますか？
8. 新規作成ですか？それとも、途中で離脱する人がいるチュートリアルの監査ですか？
9. 完成したチュートリアルを、学習者として最初から最後まで実行できるのは誰で、どのマシンを使いますか？
10. ページを公開する必要があるのは何日ですか？期限が厳しい場合、優先順位を1段階早く止め、離脱ビュー以降のすべての指標を先送りにします。
11. 一度限りの成果（来週のローンチに向けてページが必要）ですか？それとも、継続的に価値を生む資産（ドキュメントセットが今後2年にわたってこれを基盤にする）ですか？継続的に価値を生む資産の場合は、堅牢性の段階、付属リポジトリ、CIで実行するチェックポイントの優先順位が上がります。一度限りの場合は、この3つをすべて削除します。
12. 執筆にかけられる時間の上限は何時間ですか？また、リリースごとにこのページを担当するのは誰ですか？担当者が決まっていない場合は、仕上げの段階と付属リポジトリを完全に削除します。

以下の2つのランキング（段階的な優先順位のどこで止めるかと、KPI の優先順位）はどちらも既定値であり、絶対的なルールではありません。これらの回答と、チームについて既に把握していることに照らして、優先順位を付け直してください。既存の分析パイプラインがあれば、離脱ビューの追加はほぼ無料です。既存のサンドボックスがあれば、実データを使う段階の追加はほぼ無料です。どちらかを加えた場合は、既定の優先順位を上回ります。

ワークフロー

この手順の順番には意図があります。まず目的（ステップ 2）、次に証拠（ステップ 3）、その後にアクティビティ（ステップ 4～7）です。順番を逆にするのは、よくある失敗です。チュートリアルの手順を先に書き、後から目的を付け足すと、学習を思わせるタイトルが付いた機能紹介になってしまいます。手順が学習者のニーズではなく、製品の機能に基づいて選ばれるためです。この順序には「逆向き設計（backward design）」という名前があります（Wiggins と McTighe 著、Understanding by Design）。チームから異論が出たときは、この呼び名を使ってください。

1. モードを設定します。 既存のチュートリアルを監査する場合は、まず誰かに予備知識なしで実際に実行してもらい（ステップ 11）、実際に離脱した箇所を集めます。読むだけで書き直してはいけません。新規作成の場合は、ステップ 2 に進みます。
2. 内容を書く前に、学習者が行う動作を表す動詞で始まる一文として学習目標を書きます。それを使って、対象外とする内容を決めます。The Good Docs Project の表現は、「このチュートリアルを終えると、次のことができるようになります……」に続けて、設計する、評価する、開発する などの動詞を置くものです。学習者がそれを実行できるかどうかをテストできないなら、それは学習目標ではありません。弱い表現と強い表現の組み合わせについては、./references/worked-examples.md を参照してください。
3. 学習者が目標に到達したとどう判断するかを決めます。最終チェックポイントと、ステップ 11 で補助なしに行ってもらう応用課題を決めます。手順を 1 つでも書く前に決めてください。これが、手順の積み重ねが機能紹介へと逸れていくのを防ぎます。
4. 作成する成果物を選びます。 その概念がなければ作成できない最小のものにします。大きなプロジェクトでは、入力の手間が増えるだけで、学びは増えません。
5. 対象読者のレベルと前提条件を冒頭ではっきり示します。必要なソフトウェアは項目ごとに確認コマンドを付け、必要な知識は項目ごとにリンクを付けます。2 つのレベルを同時に対象とするチュートリアルは、どちらにも役立ちません。専門性逆転効果によれば、初心者の理解を支える同じ実例が、専門家には冗長になり、さらには有害になります。
6. 概念の段階を組み立てます（以下を参照）。各ステップで新しい概念を 1 つだけ導入し、依存関係の順に並べ、それ以外はすべて再利用します。このセクションの評価基準に照らして、どこで止めるかも決めます。
7. 手順を書きます。 各ステップには、完結した内容を表す命令形の見出し（「データベースに接続する」であり、「接続する」ではありません）を付け、アクションは正確に 1 つにします。学習者がファイルや画面を開く必要がある場合は、まずその場所を示します。概念の段階に合った形のコード、実行して得られた期待される出力、そして各ステップで失敗する可能性がある場合は、該当するトラブルシューティング項目への 1 行の案内を含めます。
8. 3～5 ステップごとにチェックポイントを配置します（基本）。各チェックポイントは検証可能な状態であり、そこから再開できる地点でもあります（以下を参照）。
9. 締めくくりを書きます。 学習者が新たにできることを示し、完成した最終成果物を 1 か所にまとめて提示します。次に読むべきドキュメントの区分も案内します。
   • 実際のバリエーションについては、ハウツーガイド。
   • 仕組みについては、リファレンス。
   • 理由については、解説。
10. 文章に対してヒューマナイザーを適用します（コードブロックには適用しません）。好みのヒューマナイザースキルを使い、モデルが語りかけるような文章ではなく、エンジニアが教えるような文章にします。
11. 以下の合格基準に照らして、宣言したレベルに合う実際の学習者とともに検証します。 合格するまで修正して再実行します。
12. 計測を設定し、記録します。 完了イベントと、チェックポイントごとの離脱状況を確認する画面を定義します。環境に永続メモリがある場合は、学習目標、対象読者のレベル、選択した環境、意図的に省いた概念を保存し、関連するチュートリアルとの一貫性を保ち、内容が相互に矛盾しないようにします。

概念の段階

製品のアーキテクチャではなく、依存関係に基づいて概念を並べます。次の段階を追加する前に、各段階を最初から最後まで通して確認します。

レイヤー	追加するもの	学習者が目にするもの	リリースのたびにかかるコスト
スケルトン	実行できる最小限のコード	何かが応答する	ほぼゼロです。インストールコマンドが動かなくなった場合にのみ壊れます
中核となる概念	チュートリアルのテーマとなる機能	約束された動作	破壊的変更のたびに1時間かかります。いずれにせよ必要な作業です
実データ	ハードコードされた値の代わりに学習者自身の入力	自分のデータが処理される様子	フィクスチャ、シードスクリプト、サンドボックスが必要です。スキーマ変更のたびにずれていきます
堅牢性	エラー処理、検証	意図的に処理された障害	エラーパスとその期待される出力が1つ必要です。リリースを重ねても安定しています
仕上げ	設定、テスト、構成	本番環境向けの形	継続的な作業が必要です。設定、ロックファイル、テストスイートは放っておくと劣化します

行の順序は構築する順序です（各レイヤーはその下のレイヤーを必要とするため）。そのため、これは優先順位ではありません。優先順位はどこで止めるかを決めるものです。スケルトンと中核となる概念は必須であり、これらがなければ目的を達成できません。

• 価値：中核となる概念 > 実データ > 堅牢性 > 仕上げ
• 作成と保守にかかる労力：仕上げ > 実データ > 堅牢性 > 中核となる概念 > スケルトン
• 効率：中核となる概念 > 堅牢性 > 実データ > 仕上げ

堅牢性は価値では実データに劣りますが、効率では上回ります。意図的なエラーパスは1時間で記述でき、リリースを重ねても使い続けられます。一方、実データでは、次のスキーマ変更で壊れるフィクスチャやサンドボックスが必要になります。標準の終了地点：中核となる概念と堅牢性。 学習者自身の入力が目的に含まれている場合や、サンドボックスがすでに存在していて、追加の負担がほとんどない場合は、実データまで進めます。

この順序では仕上げが後回しになります。本番環境向けの形は、読者が最終的に必要とするものであり、維持に最もコストがかかるものです。それでも、チュートリアルが社内ツールやエンタープライズツールへのオンボーディングも兼ねる場合は、仕上げを優先します。その場合、本番環境向けの形そのものが目的だからです。ヒアリングでページの担当者が決まらなかった場合は、仕上げの段を計画の最下部に置くのではなく、計画から削除してください。担当者のいない段はスコープとして再び現れ、やがて劣化します。

この梯子を押し付けではなく、学習に役立てるためのルールが2つあります。

各ステップで新しいことは1つだけにします。 1つのステップで不慣れな概念を2つ導入して結果が間違っていた場合、学習者はどちらが原因かわからず、ページではなく自分を責めてしまいます。

ガイダンスを段階的に減らします。 初期のステップでは完成例をすべて提示し、後半のステップでは提示を減らしていき、最後には学習者自身がコードを書けるようにします（下の段階表を参照）。ステップ7でもステップ1と同じ量をコピー＆ペーストさせるチュートリアルでは、何も学べません。学習者は動くアプリを手にしますが、応用できるスキルは身につきません。

段階	コードブロックの形式
初期	ファイル全体。すべてのインポートを含み、貼り付けるだけで実行できます
中盤	追加する行のみ。ファイル名を示し、挿入位置も明記します
後半	要件と期待される出力を提示します。答えはワンクリックで確認できます

ガイダンスを段階的に減らすことは、認知負荷に関する確立された知見です（Renkl ら）。上記の3段階の分け方は、このスキル独自の基本形式であり、知見そのものの一部ではありません。

「ワンクリックで確認できる」とは、完成したコードをひとかたまりで提示することではありません。答えの見せ方に段階をつけ、ほぼ完成している学習者には、行き詰まりを解消するための最小限の助けを与えます。

1. 関連するリファレンスページへの案内。
2. 擬似コード。
3. 重要な行を空欄にした解答。
4. 完全な解答。 この番号は、執筆する順序ではなく、学習者がたどる段階を示しています。一部の段階しか用意できない場合は、執筆時間あたりの価値が高い順に並べます：穴埋め済みの解答 > 手がかり > 完全な解答 > 擬似コード。

• 穴埋め済みのブロックは、完全な解答から3行を抜いたもので、最も多くを学べます。
• 手がかりはリンクです。
• 完全な解答はそのまま貼り付けられるため、学べることは最も少なくなります。
• 擬似コードは、API が変わるたびに書き直して、穴埋め済みのブロックにすでに書かれている内容を説明する文章です。

第3段階が効果的なのは、完成問題効果（Paas、1992）によるものです。途中まで埋められたブロックは、完成したブロックと同じくらい学習効果があり、学習者にはより多くの思考を促します。このセクションで挙げた認知負荷の効果は、形式を正当化するために使い、数値を導き出すためには使わないでください。

学習者の注意を引くものはすべて、学習対象の概念から差し引かれます。説明のないフラグ、別のパッケージマネージャー、名前を変更した変数、余計な警告などです。スターターリポジトリやスキャフォールディングコマンドを使って、ボイラープレートをあらかじめ用意してください。入力することから学べることは何もありません。

チェックポイント

チェックポイントがあれば、学習者は自分の読み取りを信じなくても、システムが説明どおりの状態にあることを確認できます。必ず、次の3つを揃えてください。

1. 観測可能な出力を生成するコマンドまたは操作。
2. 正確な期待される出力。
3. 一致しない場合の復旧方法。トラブルシューティングの項目、または正しい状態に戻せるスナップショットです。

チェックポイントには、クイックスタートの期待される出力の行にはない役割もあります。チュートリアルは中断して再開するのに十分な長さがあるため、各チェックポイントを再開ポイントにしてください。たとえば、コンパニオンリポジトリのブランチやタグ、冪等なシードスクリプト、または「ステップ N にリセットする」手順を文書化します。翌日に戻ってきた学習者は、最初からやり直すのではなく、最後に通過したチェックポイントから再開できます。

公開済みの手順とブランチの内容が乖離しているコンパニオンリポジトリは、リポジトリがないよりも悪い状態です。学習者は説明文よりコードを信頼し、文章では説明されていない状態に陥ります。

表現と信頼性

Diátaxis は制約を率直に述べています。「チュートリアルは自信を与えるものでなければならない」、そして「何も問題が起きないほどよく構成され、すべてのユーザーが毎回確実に進められるものであるべきだ」と。一つの手順が失敗する損失は、三つの手順がうまくいくことで得られるものより大きくなります。学習者は自分には無理だと考え、離れてしまいます。

• 「このチュートリアルでは、〜します」と書き、続けて「まず、x を行います。次に、y を行います」と書きます。全体の流れには一人称複数を、操作には命令形を使います。
• 結果の前に、期待する状態を示します。「出力は次のようになります」。
• 見落とされがちな点に注意を促します。「ここに注目してください」「忘れないでください」。
• 最後に達成を伝えます。「これで、〜を作成できました」。
• 選択肢や代替案は提示しません。製品を理解する前に学習者が解決しなければならない分岐は、進行を妨げます。
• 説明は一文にとどめ、詳しくはリンク先に委ねます。説明は最も抗いがたい誘惑であり、作業の途中で学習者を離れさせる最も手っ取り早い方法です。Procida は Diátaxis の枠組みの外でも、同じ姿勢を具体化しています。「私が何を説明し、何を言うかはほとんど関係なく、重要なのは、人々が学べるように何をさせるかだけだ」という原則です。彼はこの原則を、教わるより実践するほうが CSS を早く習得した 10 代のクラスで学んだと述べています。
• 各手順では、意図的にパターンを繰り返します。Diátaxis は「反復は最良の教師ではありません。時には唯一の教師です」と述べています。冗長に見えるのは執筆者だけです。
• 失敗した人を責めるような復旧案内は書きません。「先にシークレットを設定しておくべきでした」では、行き詰まった学習者に自分の失敗だと思わせてしまいます。代わりに状態を説明します。「シークレットが設定されていない場合、この処理は 401 を返します。設定してから再試行してください」。

望ましい困難（Bjork の用語で、習得を遅らせる一方、定着を促す困難）と、Diátaxis の摩擦ゼロの原則は矛盾しているように見えます。しかし、ページの異なる部分を対象としているため、矛盾はありません。本道（環境、コマンド、学習者が入力するコード）を支配するのは信頼性であり、そこで起きる失敗はすべてあなたの不備です。

学習者が定着させるべき概念には、意図的な困難を加えてもかまいません。ただし、合格したチェックポイントの後に、任意の追加項目として明確に示し、答えも用意してください。

• 実行前に出力を予想する。
• わざと何かを壊し、エラーを読む。
• パラメーターを一つ追加して機能を拡張する。

省略や曖昧さによって生じる困難は、望ましい困難ではありません。学習者はそれを自分の失敗として受け止め、離れてしまいます。

対象者と状況の分け方

成果物は、どの読者にとっても同じです。目標も、段階も、チェックポイントも変わりません。訪れる人によって変わるのは二つです。

個人学習者、セルフサービス型の製品。 学習者はいつでも離れることができ、あなたに何の義務も負いません。

• 目に見える成果を最初に示します。
• 手順全体を無料プランの範囲内に収めます。
• 最後のチェックポイントより前に、課金案内を表示してはいけません。

社内ツールまたはエンタープライズツールのオンボーディングを受けるチームメンバー。 離れることはできないため、失敗の形はタブを閉じることではなく、気づかれないまま誤解することです。

• 手順 1 の前に、必要なアクセス権と、それを付与する担当者を明記します。
• インターネット接続を前提とするすべてのコマンドに、オフラインまたはオンプレミスの代替手順を用意します。
• レビュー担当者に提示できるチェックポイントを追加します。

合格基準

チュートリアルの合格基準を公開している人はいないため、この6項目の基準はあくまでたたき台だと提案時に伝え、これに照らして評価する前に、ユーザーが項目を削除したり追加したりできるようにしてください。根拠があるのは、基準4の15～60分という範囲だけです（The Good Docs Projectが示している範囲です）。

宣言した対象者レベルに該当する人が、クリーンなマシンで最初から最後まで実行し、次の6項目すべてを満たしたら、チュートリアルの完成です。

1. 各ステップの実際の出力が、ドキュメントに記載された出力と一致している。
2. 作者の助けを借りずに、すべてのチェックポイントを通過できる。
3. ソフトウェアや知識など、前提条件がステップ1の後に一切判明しない。
4. 所要時間が提示した見積もりの範囲内であり、全体で15～60分以内である。
5. 学習者が、手順を説明していない別のバリエーションで、目的をもう一度自力で達成できる。
6. 途中でやめたり、ためらったりした箇所がすべて特定のステップに結び付けられ、平均化されずに修正されている。

基準5こそが、チュートリアルと長いクイックスタートを分けるものです。ここで失敗する場合、学習の足場を外すのが遅すぎたか、まったく外していなかったということです。学習者はコピーを繰り返して、動くアプリを作っただけです。

KPI

Kirkpatrickの4段階でこれらを分類し、落とし穴を明らかにします。研修チームはレベル1～2を測定しただけで止めてしまうため、完了率が高く行動変容のないチュートリアルが、何年もの間、成功と見なされてしまいます。

各行は、計測の実装にかかる時間あたりの価値が高い順に並んでいます。レベル順ではありません。

指標	レベル	計測の実装コスト	読み取り方
初回実行での転送テスト合格率	2 学習	ほぼゼロです。合格基準の項目 5 ですでに実行しているため、結果を記録するだけです	チュートリアル内で、スキルが身についたのか、アプリをつなぎ合わせただけなのかを示す唯一の証拠です
チェックポイントごとの離脱率	1 反応	1 時間です。チェックポイントごとにイベントを 1 つ設けます。チェックポイントはすでに存在します	離脱が集中するチェックポイントが 1 つあれば、難しい概念ではなく、手順に問題があります。概念を中心に書き直す前に、その手順を修正します
特定の手順を引用したサポートへの質問や問題	2 学習	収集はほぼゼロですが、継続的に確認する必要があります	1 件ごとに、誤っている、または曖昧な指示を修正できる文章まで特定できます
完了率（最終チェックポイント到達数／開始数）	1 反応	離脱イベントがあれば無料です	ページが注目を維持できているかを示します。学習できた人がいるかどうかは分かりません
完了時間の中央値と提示した所要時間の比較	1 反応	離脱イベントがあれば無料です	30 分と提示しているのに実際には 70 分かかるなら、ページが最初に掲げた約束に反しています。再計測してから提示時間を改めます
完了者のうち、1 週間以内に製品内で同じタスクを実行した人の割合	3 行動	継続的な対応が必要です。学習用の場と製品で同じ ID を共有する必要があり、公開前に決めておきます	製品内で繰り返し実行されないまま完了しているなら、チュートリアルが教えたのは製品ではなくチュートリアルです

• 価値：行動の割合 > 転送テスト > チェックポイントごとの離脱率 > サポートへの質問 > 完了率 == 完了時間の中央値
• 実装の手間：行動の割合 > サポートへの質問 > チェックポイントごとの離脱率 > 完了率 == 完了時間の中央値 > 転送テスト
• 効率：転送テスト > チェックポイントごとの離脱率 > サポートへの質問 > 完了率 == 完了時間の中央値 > 行動の割合

完了率と完了時間の中央値が両方の軸で同順位なのには、理由があります。どちらも同じ開始イベントと終了イベントのペアから得られる指標であり、片方だけを計測することはできず、どちらも問題箇所を特定できません。デフォルトでは、最初の 2 つを計測し、3 つ目を確認します。 残りは、ページで 1 回分のコホートを実施してから追加します。

この順序では、表中で最も価値が高く、製品が変化したことを示す唯一の指標である行動の割合が後回しになります。それでも、チュートリアルがアクティベーションのステップとして数えられる場合や、ページ自体の人員を正当化するよう求められた場合は、ほかの指標より優先してください。その問いに答えられる、より低コストの指標はありません。また、最初のコホートを計測可能にするには、公開前に ID の仕組みを整える必要があります。

外部の数値を使って目標を設定しないでください。開発者向けチュートリアルの信頼できる完了率ベンチマークは公開されていないため、それぞれの数値をこのチュートリアルの以前のバージョンと比較します。 公開済みのパッケージを使って、各チェックポイントに対応するブランチをCIで定期的に実行し、コミット時にも実行して、陳腐化を防ぎます。チュートリアルが壊れるのは、ドキュメントのリポジトリが変わったときではなく、製品が変わったときです。

呼び出し方と返す内容

回答する前に、与えられた依頼が3つの形式のどれに当たるかを特定してください。ここで間違った成果物を返すことが、最も大きな失敗です。完成したように見えてしまうからです。

ユーザーの依頼	モード	返す内容
「SDKからレスポンスをストリーミングする方法を教えるチュートリアルを書いてください」	新規作成	インタビューの後、アウトラインテンプレートに沿って作成したページ
「ウェブフックのチュートリアルを最後まで読んでもらえません。修正してください」	監査	手順ごとにまとめた優先順位付きの問題リスト、その後、問題のある手順を書き直したもの
「これはチュートリアルですか、それともハウツーですか？」	スコープ判定	分類、その理由、もう一方の回答を担当する関連スキル

新規作成。 references/tutorial-outline-template.md の各セクションに沿って、完成したページを提出してください。期待される出力のブロックがプレースホルダーのままのページは、決して公開してはいけません。実行されていない出力ブロックこそ、このスキルが防ごうとしている問題です。コマンドを実行できない場合は、未検証のブロックを示し、作成者に実行リストを渡してください。

監査。 説明文ではなく、表を返してください。列には、手順番号、問題点、4種類のイベント（問題、隠れた前提条件、概念の不足、手間。詳しくは references/verification-protocol.md を参照）、修正内容を含めます。行の順序はページの掲載順ではなく、各手順によって進行を妨げられる学習者の数に基づいて決めてください。

どちらのモードでも： 始める前に、目的と対象読者のレベルを明確にしてください。これを推測すると、機能紹介のような内容になってしまいます。

失敗のパターン

症状	対処
最初の操作の前に、アーキテクチャや理論の説明から始まる	最初の操作に進み、概念の説明はリンク先のドキュメントに委ねます
1つのステップで新しい概念を2つ同時に紹介している	分割します。それぞれに、観察可能な出力を用意します
最後のステップでも学習者がコピー＆ペーストしている	もっと早い段階で手助けを減らします。差分ブロックに切り替え、次に要件だけを提示します
チュートリアルがOS、フレームワーク、パッケージマネージャーによって分岐する	1つに絞り、他のパターンはリンクで案内します。手順の途中で分岐させないようにします
チェックポイントに「このような結果が表示されるはずです」とあるが、正確な出力がない	実際の実行で得られた出力をそのまま貼り付けます
関連リポジトリのブランチと手順が一致していない	公開済みの手順からブランチを再生成し、それぞれをCIでテストします
実行に90分かかる	チェックポイントで分割し、順序を明記した2つのチュートリアルにします
誰もが同じステップで止まる	そのステップに計測を追加し、初見の状態で再実行して、周辺の説明文ではなくステップ自体を修正します
チュートリアルを装った機能紹介	目的に立ち返り、目的に役立たないステップをすべて削除します
初心者とエキスパートの両方を同時に対象としている	対象レベルを1つ選んで明記し、もう一方の読者向けの情報は別の場所にリンクします
トラブルシューティングの項目が「〜できているはずです」という表現になっている	読者に責任を押しつける表現を書き換えます。行き詰まった学習者は、それを自分への非難と受け取り、タブを閉じてしまいます
このスキルのしきい値を業界標準としてチームに引用している	引用する前に references/published-findings.md を確認します。ここにある数値の大半は、独自に設定した基準値です

参考資料

• ページの骨組みと各セクションのルールについては、./references/tutorial-outline-template.md を参照してください。
• 手順、段階的な支援の縮小、チェックポイント、監査出力の良い例と悪い例については、./references/worked-examples.md を参照してください。
• 学習者が実行するテストプロトコルと、チェックポイントを維持する CI ジョブについては、./references/verification-protocol.md を参照してください。
• 各ルールの出典と、このスキル独自の基準値については、./references/published-findings.md を参照してください。
• サンプルのポリシー、テスト、言語ごとの同等性については、samber/developer-relations-skills@docs-code-sample-standards を参照してください。
• 手順からリンクするエラーページについては、samber/developer-relations-skills@developer-troubleshooting-docs を参照してください。
• ハウツー、リファレンス、解説の中でチュートリアルをどこに位置づけるかについては、samber/developer-relations-skills@developer-docs-structure-audit を参照してください。
• カリキュラム、コース、認定については、samber/developer-relations-skills@developer-education-strategy を参照してください。
• 手順を追うチュートリアルではなく、何かをどのように構築したかを物語形式で伝える記事については、samber/developer-relations-skills@engineering-blog-post を参照してください。
• チュートリアルではなく、知識のある読者が必要とする目標指向のハウツーについては、samber/developer-relations-skills@developer-how-to-guide を参照してください。