IbrahimSobh/content-explainer-slide

コンテンツ解説スライド

技術的な成果のストーリーを1枚の画像で構築します。何に気づいたか、何が問題だったか、何を行いなぜ各ステップが機能するのか、すべての数字の出所、そして何を達成し何を学んだかを示します。

基準はジュニアエンジニアにとって100%明確で直感的であることであり、100%詳細であることではありません。この基準は実際のレビューラウンドから来ています。用語が未定義、数字の出所が見えない、ステップの理由が脚注に隠れている、カードに空白領域があるたびに、読者は「これは何？」「30はどこから来た？」「なぜそれが機能するの？」と質問し、スライドはもう1ラウンド必要でした。以下のすべてのルールは、読者が質問する前にスライド上でそれらの質問に答えるために存在します。

完成したスライド計画の実例（ニューラルネットワークの「ニューロン手術」実験）は references/worked-example.md にあります。最初のスライドを計画する前に一度読んでください。ルールを適用したときの各カードの外観が示されています。

ステップ0 — 出力形式を尋ね、ファクトシートを作成する

出力形式を尋ねる（描画の前に一度）

ユーザーがまだ指定していない限り、希望する出力形式を尋ねます。

• matplotlib（Python）によるPNG — 入力にデータ、モデル、ログ、結果ファイルがある場合に最適です。スクリプトがこれらのファイルから直接スライド上のすべての数値を計算できるためです（手入力の数値は不要）。JPGコピーもエクスポートします。
• PNGにレンダリングされたHTML/SVGページ — 入力がテキストのみ（論文、ドキュメント、メモ）の場合、またはタイポグラフィとレイアウトの洗練さが数値の計算よりも重要な場合に最適です。ヘッドレスChrome/EdgeでPNGにレンダリングされます。
• 両方 — 同じスライド計画、2つのレンダリング。

自分の推奨を理由とともに述べてください（データ入力 → matplotlib、テキスト入力 → HTML）。ユーザーに尋ねられない場合（自動実行）、そのルールで選択し、どちらを選んだか、その理由を述べてください。

ファクトシートを作成する

デザインを始める前に、スライドで使用する可能性のあるすべての事実をリストアップします。各事実について記録します：

事実	値	測定対象（どのデータ/どのセクション）	ソース（ファイル+スクリプト、または論文のページ/表）

次に：

• 事実を相互確認し、他の事実や草案テキスト（投稿、アブストラクト、README）と照合します。すべての不一致を今解決してください。スライドが38と言い、投稿が36と言っている場合、信頼を損ないます。これらの不一致は通常、2つの場所が「同じ」数値を異なる方法で計算したことから生じます（異なるサンプルサイズ、異なるしきい値）。
• データ分割を記録します。メソッドの構築に使用されたものと、テストのために保留されたもの。スライドはこれを明示する必要があります。なぜなら、「結果は見たことのないデータでも有効か？」は技術的な読者が最初に尋ねる質問だからです。
• 2つのモード：
  • データモード（結果、モデル、CSV、ログが存在する）：描画スクリプトがそれらをロードし、レンダリング時にすべての数値を計算します。
  • ソースモード（テキストのみ）：すべての数値はソースからコピーされ、ファクトシートは引用元（ページ、表、図）を示します。ソースが述べている範囲を超えて数値を発明したり丸めたりしないでください。

ファクトシートをスライドの隣に保存し（<name>_facts.md）、後で編集しても一貫性が保たれるようにします。

ステップ1 — ストーリーを見つける（3～6枚の番号付きカード）

各質問に一文で答え、それぞれが1枚のカードになります：

1. 発見/コンテキスト — 何に気づいたか、または設定は何か。
2. 問題 — 何が間違っているか、または不足しているか、測定されたもの。複数の問題がある場合は名前を付けます（問題A、問題B）。対象とするものと、意図的に対象としないもの、およびその理由を述べてください。チャートに弱い項目があり説明がないのを見ると、読者はミスを想定します。
3. 手法 — 1つのケースのレシピをステップとして。
4. 1つのケースからすべてのケースへ — レシピがどこにでもどのように適用されたか、数を決定したルール、およびカウント。各修正をそれが解決する問題とペアにします（「修正A → 問題A」）。
5. 結果 + 教訓 — 何が変わったか、どの程度確かか、それが教えること。

同じことを言うカードは統合します（冗長なカードは毎回レビューで削除されました）。小規模な入力の場合、カード3と4は統合してもよいし、スライドを3枚のカード（問題 → 手法 → 結果）にすることもできます。最大6枚まで。それ以上はデッキであり、スライドではありません。

ステップ2 — 見出し

上部に1行または2行：驚くべき事実 + 取られたアクション。例：「M個の部品のうちN個が何もしていなかった。そこで彼らは仕事を得た。」見出しは人々がスクロールを止める理由であり、カードはそれを信頼させる理由です。見出しの数字はファクトシート/スクリプト変数から取得し、手動で入力してはいけません。

ステップ3 — カードのスケルトン（すべてのカードで同じ）

• 番号 + アクセントカラー。 各カードには大きな番号（1～5）と独自のアクセントカラーがあり、ボーダーとハイライトに使用されます。番号は読む順序を与え、色は後続のカードが以前のカードを参照できるようにします（「カード4の11個の検出器」）。
• タイトル = カードが答える質問。
• 1つの太字の要点文 = 答え。
• 1つのメイン図。 手法カードはステップセルのグリッドを使用し、結果カードはチャートと説明パネルを使用する場合があります。
• データラベル — このカードが使用するデータとその理由（「60,000枚のトレーニング画像のうち18,000枚（30%）— 残りは最終チェックを公平にするために未使用のまま保持」）。
• 短い脚注 — 注意点のみ。理由は脚注に決して入れません（ステップ4を参照）。

ステップ4 — 手法カード：WHAT / 画像 / WHY セル

手法を3～5個の番号付きセル（4つの場合は2×2グリッド）に分割します。すべてのセルは同じ3つのバンドを持ちます（上から下へ）：

1. キャプション（WHAT） — 何と何を比較するかを示す具体的なアクション：「ステップ2のパターンとNEW画像（見たことのない画像）を比較する」であり、「それがマッチングされる」ではありません。
2. 画像 — データまたはソースからの実際の例で構築：実際の入力、実際の中間結果、実際のスコア。実際の例こそが抽象的なステップを信頼できるものにします。一般的なアイコンは何も教えません。
3. WHYボックス — 全幅、固定高さ、視覚的にスタイル付け（色付き背景、「WHY？」ラベル）。ステップが機能する理由を説明します。

WHYは画像内に目立つように配置する必要があります。レビューでは、脚末に置かれた理由は毎回見落とされ、読者は繰り返し尋ねる必要がありました。セル内では、読者が尋ねるであろう質問に答えてください：

• なぜこの選択が明白な選択ではないのか？（例：なぜ正しいクラスの平均を引くのか）
• これは何に影響を与えず、なぜか？（例：「'3'を下げることしかできません。別のクラスがすでに勝っている場合、何も変わりません」）

メカニズムをbefore → afterとして示します：スコア/状態の小さなパネル（Before）、矢印、パネル（After）、勝者に✓/✗、矢印に短い注釈（「2番目に高いものが勝つ」）。パネルのタイトルが下に収まらない場合は、横に配置します。

画像が現実を単純化している場合（ピクセルを表示しているが、実際の計算は内部特徴を使用している）、脚注でその旨を述べてください。単純化について正直であることは1行のコストであり、「それはどうやって機能するのか」というコメントを防ぎます。

実例を**「例:」**としてマークし、一般則を述べてください（「30個すべての検出器で同じレシピ」）。そうしないと、読者はメソッドがその1つのケースだけをカバーしていると思ってしまいます。

ステップ5 — すべての数字をトレーサブルにする

• 各数字の出所を可視化されたチェーンとして表示します：「21例 → 3スタイル → 3検出器」、「11 + 19 = 30 / 36（6は予備）」。合計は視覚的に足し算できる必要があり、余りには理由が必要です。
• カウントを生成した選択ルールとしきい値を述べてください（「スタイルには≥2例が必要」、「学習するには少なすぎるため<3例のミスはスキップ」）。
• データが異なるソース（ラベル付き vs マイニング、測定 vs 推定）から来た場合は、凡例とともに視覚的（濃い vs 薄いバー）に表示します。
• 最初に登場する表記を説明してください（「×N = そのミスに対するN個のスタイル検出器」）。
• データモードではスクリプトがすべての数値を計算します。テキスト文字列は変数（f-strings/テンプレート値）を使用します。手入力された数値はデータと同期しなくなり、これは実際に間違ったスライドを引き起こしました。

ステップ6 — 正直な結果、すべての変更を説明

• メソッドの構築に決して使用されなかったデータに対するBefore → After。2つ目の未使用セットが存在する場合はそれを確認します。
• 利益と損失の両方を示します（「34修正、9破損」）。利益のみの結果は、都合の良い結果だけを選んだように読めます。
• 統計は平易な言葉で（「運で約600万分の1」）、専門用語は小さく、または脚注に。
• 項目ごとの変化チャート（After − Before、正/負/ゼロで色分け）および「なぜ各項目が変化したか」パネル：なぜ利益が発生したか、なぜ損失が発生したか、追加の副作用。損失を理由なしにリストすることは、最悪の解釈を招きます。

ステップ7 — 平易で一貫した言葉

• 最初の使用時にすべての用語を数語の平易な言葉で定義するか、平易な言葉に置き換えます。
• スライド全体で概念ごとに1つの言葉（「予測」はどこでも使い、「答え」と時々使わない）。
• スライド上で定義されていない限り、内部ニックネームは使用しません（「セットA」、「ひねり」、「ラッキーサイドエフェクト」、「×3」）。
• すべての主張はチャートと一致する必要があります。チャートがテキストで扱われていない奇妙なことを示している場合、それに対処してください。

ステップ8 — 凡例と色

• すべての色、シェード、矢印、記号はそれが現れる場所で説明されます。分岐する画像には「赤 = Xのみ、青 = Yのみ」。
• スライド全体で1つの色の意味：例：赤 = 問題/削除、緑 = 修正/良好、グレー = 中立。カードのアクセントカラーはこれらの意味的な色とは別です。
• グループ化されたアイテム（1つのミスのスタイル、1つのステップのバリアント）は、グループがぼやけないように目に見えるボックスに配置します。

ステップ9 — 結論と教訓のバナー

• 結論バナー（緑色の色合い）：示されたこと、その規模と限界を含む（「小さいが現実の利益であり、新しいデータでも有効」）。
• 教訓バナー（スライド下部）：読者が他の問題に持ち帰れるもの。

ステップ10 — レイアウト

• 16:9（例：150 dpiで16×9インチ、または1600×900 pxのキャンバス）。カードはストーリーの順に左から右に読みます。
• コンテンツに応じてカードのサイズを調整します。手法カードは通常最も幅広くなります。大きな空白領域を作らないでください。カードに余裕がある場合は、チャートを広げるか、テキストパネルをスペースに移動します。
• テキストの重なりを避け、ラベルはボックス内に収めます。長い行は折り返し、フォントサイズを電話での可読性（16×9インチで約7.5ptが下限）よりも小さくしないでください。
• レイアウトコードについては references/matplotlib-recipes.md（PNG）または references/html-recipes.md（HTML）を参照してください。 scripts/slide_kit.py はmatplotlibヘルパー（カード、ステップセル、WHYボックス、Before/Afterスコアパネル、バナー、PNG+JPGエクスポート）を提供します。それらを書き直すのではなくインポートしてください。

ステップ11 — レンダリング、検査、修正、繰り返し

1. 画像をレンダリングします。
2. 実際の画像を見ます — PNGを開き、各カードにズームインします（必要に応じてトリミング）。「収まるはず」のコードが収まらないことはよくあり、重なりやクリップされたテキストはレンダリングでのみ見えます。
3. references/checklist.md をカードごとに、ジュニアエンジニアが初見で見るように確認します。
4. 修正、再レンダリング、再確認。チェックリストに合格しないスライドをユーザーに見せないでください。

ステップ12 — バリエーションと最終チェック

• 詳細版（技術者向け、すべての数値）。簡易版を幅広い読者向けに提供します：同じストーリー、正確な数値は少なめ。
• LinkedIn/X用にJPGコピー（透明なし）をエクスポートします。
• スライドまたは関連する投稿に表示されるすべての外部の主張や引用を公開前に検証します。検証できなかったものはフラグを立てます。
• 納品物：PNG（+ JPG）、描画スクリプトまたはHTMLソース、およびファクトシート。 linkedin-arabic-science-post、tweet-post、または figure-animator を使用して、完成したスライドから投稿やアニメーションバージョンを生成できることに言及します。