tech-tutorial

技術チュートリアル

優れた技術チュートリアルの目的は一つです。読者を、何かのやり方を知らない状態から、自分でできる状態へと導くことです。 そのためには、動作するコード、具体的な手順、そしてうまくいかない場合について率直に説明することが必要です。 このスキルでは、この基準を満たすチュートリアルの構成、執筆、検証方法を説明します。

使用する場面

• ライブラリ、CLI ツール、API の入門ガイドを書くとき
• 読者がターミナルで手順に沿って進めるチュートリアルを作成するとき
• 実践的な演習を通じて技術的な概念を説明するとき
• API リファレンスドキュメントを補完するハウツーを作成するとき

使用しない場面

• API リファレンスドキュメントを生成するとき（scribe:doc-generator を使用）
• 既存の文章を整えるとき（scribe:slop-detector を使用）
• 実行可能な手順を含まない、概要レベルのアーキテクチャ説明を作成するとき
• 実践的な要素のない概念的なエッセイを書くとき

方法

ステップ 1：対象範囲と読者

一行も書き始める前に、次の質問に答えてください。

• 誰に向けたものですか？レベルを newcomer、practitioner、expert のいずれか、または一行の persona で明示してください。チュートリアルの既定値は newcomer です。そうでない場合は、代わりにどのような前提を置くのかを明記してください
• 読者は何人ですか？それぞれ何回読むでしょうか？
• 読者は最後までに何を作る、または達成するのでしょうか？
• 読者が必ず持ち帰るべき一文は何ですか？ （トピックではなく、主張です）
• 読者がインストールしておく必要のある前提条件は何ですか？
• 明確に対象範囲外とするものは何ですか？

これらの回答を、ドラフトのヘッダーブロックとして書き留めてください。 「何を達成するのか」という質問に一文で答えられない場合、対象範囲が広すぎます。主張を一文で述べられない場合は、まだ執筆を始める準備ができていません。

読者数と閲読頻度は、読者時間の予算に反映されます（scribe:slop-detector モジュールの document-economy.md を参照）。 500 人の開発者が一度読むチュートリアルは、読者時間 40 時間分の資産です。それに見合った時間を執筆にかけてください。

レベルによって、ドラフトに含めてよい内容が決まります。依頼で読者が指定されていない場合は、推測せず、質問してください。scribe:slop-detector モジュールの audience-targeting.md に、レベル表とソクラテス式の質問集があります。

newcomer 向けのチュートリアルでは、最初から最後まで動作する一つの手順を扱います。別の方法、内部の仕組み、一見明白な方法がうまくいかない理由は、expert 向けの内容です。これらは docs/deep-dive/<topic>.md に移し、誰を対象とする詳細解説なのかを明記した一行のリンクを冒頭に置いてください。レベルに合わせるために、これらを削除してはいけません。三つの方法を比較するために立ち止まるチュートリアルは、読者をできない状態からできる状態へ導く役目を果たせなくなっています。

ステップ 2：アウトライン

読み込む：@modules/outline-structure.md

文章を書く前に、セクションごとのアウトラインを作成してください。各セクションには、そのセクションで読者が行うこと、または学ぶことを一行で記述してください。 標準的なセクションの順序と、セクションの種類ごとの目標文字数については、アウトラインモジュールを参照してください。

ステップ 3：コード例を先に作成する

読み込む：@modules/code-examples.md

文章より先にコードを書いてください。 各スニペットは、チュートリアルに掲載する前に、実際の環境で実行してください。 補足するのは、わかりにくい行だけにしてください。 書式とエラー処理のルールについては、コード例モジュールを参照してください。

ステップ 4：コードを中心に文章を書く

文章は、コードが何をするのか、なぜそうするのかを説明するためにあります。 次のルールに従ってください。

• 各手順は一段落で説明します。何を実行するのか、何をするのか、何を期待できるのかを述べます
• 各コマンドブロックの後に、期待される出力を示します
• 全体を通して、一貫して二人称（「あなた」）を使います
• 読者が次に何をするかを説明してはいけません。次の手順をそのまま提示してください

ステップ 5：複雑さを段階的に高める

読み込む：@modules/progressive-complexity.md

最小限の動作する例から始めます。 バリエーションやエッジケースを追加するのは、基本の例が動作した後にしてください。 段階的に複雑さを高めるルールと進行のガイダンスについては、段階的な複雑さのモジュールを参照してください。

Step 6: 冗長な表現のチェック

下書きを作成したら、次を実行します。

Skill(scribe:slop-detector)

先に進む前に、Tier 1 の指摘をすべて修正してください。 特に次の点に注意してください。

• Tier 1 の語彙上の冗長表現（scribe:slop-detector の単語リストを参照）
• 形容詞を3つ並べる表現（「高速で、効率的で、信頼性が高い」など）
• 分詞構文を文末に置く表現（「……し、これにより……が可能になります」など）

Step 7: 品質ゲート

次のチェックリストに照らして、完成したチュートリアルを確認してください。

内容：

• すべてのコードブロックをテストし、記載された出力が得られる
• 前提条件のセクションに、該当する場合は正確なバージョンを記載している
• 各ステップに期待される結果を記載している
• トラブルシューティングのセクションで、よくある失敗モードを少なくとも2つ取り上げている

文単位：

• Tier 1 の冗長な表現がない
• 1000語あたりのダッシュの数が2未満である
• 箇条書きの割合が40％未満である
• 行の長さが80文字になるように改行されている

ドキュメント単位（document-economy モジュール）：

• Step 1 の主旨が導入段落に含まれている
• 結びで主旨を繰り返している（できればチュートリアルの中盤でも）
• 直前の内容を列挙し直す「まとめ」セクションがない
• セクションの冒頭で、その見出しを言い換えていない

対象読者（audience-targeting モジュール）：

• Step 1 で対象レベルを宣言している。未指定の場合は確認している
• すべてのセクションがその対象レベルに適している
• 対象レベルから外れる詳細は削除せず、リンク先の詳細解説に移している

必須の進捗項目

1. tech-tutorial:scope-defined - 対象読者、目標、対象範囲外の項目を記録済み
2. tech-tutorial:outline-approved - セクション構成を確認済み
3. tech-tutorial:code-tested - すべてのコードスニペットを実環境で検証済み
4. tech-tutorial:prose-drafted - 手順の説明文を作成済み
5. tech-tutorial:slop-scanned - 冗長な表現の検出に合格済み
6. tech-tutorial:quality-verified - 品質ゲートのチェックリストをクリア済み
7. tech-tutorial:user-approved - 最終承認を受領済み

モジュールの参照先

• セクションの順序と長さの目安については、modules/outline-structure.md を参照してください
• スニペットの書式と注釈のルールについては、modules/code-examples.md を参照してください
• 段階的な構成とペース配分については、modules/progressive-complexity.md を参照してください

他のスキルとの連携

スキル	使用するタイミング
scribe:slop-detector	下書きの作成後、承認前
scribe:doc-generator	付属の API リファレンスのセクションを作成するとき
scribe:style-learner	既存のチュートリアルの文体に合わせるとき

完了条件

• 下書きの開始前にチュートリアルの構成を確認済み
• 対象レベルを下書きの開始前に宣言済み
• すべてのコードスニペットを実環境でテスト済み
• 冗長表現のスコアが 1.5 未満（問題なし）
• 対象レベルから外れる内容を、読者の導線に残したり削除したりせず、リンク先の詳細解説に移動済み
• 品質ゲートのチェックリストに合格済み
• ユーザーの承認を受領済み