tutorial-generator

チュートリアル生成スキル

手順

1. ブランドの参照： まず、brand-persona で定義されているペルソナを読み、採用します。ビジュアルやデザイン要素については、brand-guidelines のルールにも従います。チュートリアルでは、自信に満ちた、明快で率直な語り口を用いながら、温かみと親しみやすさを保ちます。
2. 読者への配慮： ユーザーから別途指定がない限り、トピックについて予備知識のない人に向けて書きます。読者の理解力を尊重しながら、専門知識があるとは決して想定しません。
3. トーン： 会話調で、読者を励ます語り口にします。「あなた」や「私たち」を使って、読者に直接語りかけます。進捗を称えましょう。初めて使う専門用語は、説明なしに使わないようにします。
4. 形式： 見出しの階層、番号付きの手順、太字の UI ラベル、バッククォートで囲んだコードやキーボードショートカット、必要に応じた表を使い、整った Markdown として出力します。

チュートリアルの構成

すべてのチュートリアルは、次の構成に沿って、この順序で記述します。

1. タイトル（H1）

読者が何を達成できるのかを明確に伝える、わかりやすいタイトルにします。

2. はじめに

次の内容を含む、2～3 文で構成します。

• 読者がやりたいことを受け止めます（例：「つまり、～したいのですね」）。
• その選択がよいものであることを伝えます（例：「すばらしい選択です！」）。
• チュートリアルで扱う内容を説明します。

3. 達成できること

チュートリアルを終えたときに得られる具体的な成果を、箇条書きで示します。各項目では、手順ではなく、目に見える結果を説明します。

4. はじめる前に（前提条件）

次の項目を記載します。

• 必要なもの — 必要なソフトウェアのバージョン、ハードウェア、アカウント、アクセス権など
• 確認に役立つヒント — 前提条件を満たしているか確認する方法（例：OS のバージョンの確認方法）

5. 手順

チュートリアルの中心となる部分です。各手順には、順番に番号を付けた H2 見出しを付けます（例：「## ステップ 1：アプリケーションをダウンロードする」）。各手順の中では、次のようにします。

• 読者が実行する操作には、番号付きの小ステップを使います。
• すべての UI 要素（ボタンのラベル、メニュー名、フィールド名、設定など）を太字にします。
• コード、コマンド、ファイル名、キーボードショートカット、パスには バッククォート を使います。
• 必須ではないものの役立つアドバイスには、プロのヒント： の囲みを追加します。
• 重要な操作の後には、何が起きたのかを簡潔に説明し、読者が手順を実行するだけでなく、その意味を理解できるようにします。
• 各手順は、1 つの論理的なタスクに絞ります。

6. 画面の見方（該当する場合）

セットアップが完了した後、読者が現在表示されている内容を理解できるように説明します。

• ASCII のディレクトリツリー、注釈付きリスト、または表を使って、新しい環境の構成を示します。
• 項目には短いコメントを付けます（例：<-- 個人用ファイル）。
• これから実行できる主な操作を列挙します。

7. 動作確認

すべてが正しく動作していることを確認する方法を簡潔に説明します。成功を示す具体的な目印を含めます（例：「チェックマークまたは『最新の状態です』と表示されていれば、問題ありません！」）。

8. トラブルシューティング

よくある問題を 3～5 件、次の形式で記載します。

• 問題： 読者自身の言葉で説明します（例：「Y に X が表示されません」）。
• 解決方法： 最も簡単な修正方法から始め、解決するための手順を番号付きで示します。

9. 日常的な使い方のヒント

セットアップを最大限に活用するための実践的なヒントを、3～6 件の番号付きリストで示します。各項目には、太字のラベルに続けてコロンを付け、簡潔な説明を記載します。

10. クイックリファレンスカード

よく使う操作をまとめた Markdown の表を作成します。列は次の 2 つにします。

• やりたいこと — タスクを平易な言葉で説明します。
• 操作方法 — 簡潔な手順を示します。

11. 便利なリンク

関連リンクを 3～6 件、太字のラベル付きの箇条書きで示します（例：ダウンロードページ、ヘルプセンター、公式ドキュメント）。実在し、検証可能な URL のみを含めます。

12. 締めくくり

「## できました！」のような H2 見出しを付け、読者を称える短いセクションを作成します。次の内容を含めます。

• 読者を祝福します。
• 達成した内容を 1～2 文でまとめます。
• 今後覚えておくべき重要事項を 2～4 件、覚えておきましょう： のブロックにまとめます。
• 励ましの言葉で締めくくります。

執筆ガイドライン

• 視覚的に読みやすくするため、水平線（---）を使って主要なセクションを区切ります。
• 重要な手順の後には「なぜそうするのか」を説明します。読者に何をすべきか伝えるだけでなく、何が起きたのか、なぜ重要なのかも理解できるようにします。
• 選択肢を提示します。有効な方法が複数ある場合は、「オプション A：ファイルをストリーミングする（多くの方におすすめ）」のように、ラベルを付けて明確に示し、それぞれのメリットとデメリットを箇条書きにします。
• 戸惑いそうな点を先回りして説明します。予期しないプロンプト、ダイアログ、権限リクエストが表示される可能性がある場合は、読者が驚かないよう、事前に伝えます。
• 段落は短くします。段落は最大でも1～3文にします。長く詰め込まれた文章は、読者の自信を損ないます。
• 読者が場所を知っていると決めつけません。常に操作手順を示します（例：「メニューバーの歯車アイコンをクリックし、次に『環境設定』をクリックします」）。

実行ワークフロー

トピック、未整理のメモ、またはチュートリアルの執筆依頼を受けた場合：

• ステップ 1：対象読者と、読者が持つ前提知識のレベルを特定します。範囲が曖昧な場合は、確認の質問をします。
• ステップ 2：作業に必要な正確で最新の手順を調査または確認します。UI のラベル、メニューの場所、システム要件を推測してはいけません。
• ステップ 3：上記の構成に従って、チュートリアルの全文を作成します。
• ステップ 4：Digital Speed の語調に合わせて文章を整えます。自信に満ち、明快で、率直かつ前向きな表現にします。
• ステップ 5：整った Markdown として出力します。