A.4 コースビジュアル使用ルール
画像は装飾ではなく教材です。学習者の理解コストを下げるときだけ、追加または維持します。
先に学習の深さを確認する
レッスンを変更する前に、学習者として読み直し、ページが 3 つの層を同時に支えているか確認します。
| 学習者の層 | ページに必要なもの | 注意サイン |
|---|---|---|
| 初学者 | 小さな実行操作、平易な意味、期待される出力、失敗時の戻り道 | 用語説明はあるが、実行や確認がない |
| 実践者 | 判断ルール、よくある失敗、残す証拠、次のプロジェクト手順 | demo はあるが、結果が良いか判断する基準がない |
| 経験者 | トレードオフ、境界ケース、デバッグ信号、評価習慣、運用制約 | 用語集のようで、深く考える問いがない |
ページが短すぎる場合は、定義を増やすより、学習者が詰まる地点を深めます。良いページは、初学者が 1 つの操作を終えられ、経験者が設計や評価の論点に気づけるページです。
適切なビジュアルを選ぶ
| 学習ニーズ | 最適なビジュアル | 文字は短く |
|---|---|---|
| 新概念、章の入口、物語、比較 | image2 の教材イラストや漫画 | はい |
| 正確な数式、座標、行列、コード実行順 | SVG またはコード生成チャート | はい |
| 実プロジェクトの結果 | スクリーンショットまたは生成 mock | はい |
| 学習曲線、指標、分布 | コード生成チャート | はい |
| 参照用チェックリスト | コンパクトな表または図 | はい |
モバイルと三言語画像ルール
画像の向きは教育目的から選びます。段階的な手順、スマートフォン優先の読解、上下に説明を積みたい難しい概念には縦長 9:16 が向いています。タイムライン、左右比較、アーキテクチャ図、ダッシュボード、横方向に追う情報には横長が向いています。単一の対象、パターン、チェックリストにはコンパクトな正方形または正方形に近い画像を使えます。大切なのは、固定比率ではなく学習しやすさです。
教材画像は中国語、英語、日本語の三言語セットで生成します。三言語版は同じ場面、レイアウト、教育目的、主要な値、視覚リズムを共有し、学習者向けのタイトル、サブタイトル、ラベル、alt 文だけをローカライズします。
同じセットでは、元画像と公開画像を次のパターンでそろえます。
topic-name.png
topic-name-en.png
topic-name-ja.png
topic-name.webp
topic-name-en.webp
topic-name-ja.webp
生成後は、プロジェクトの現在の公開方法に合わせ、コースページから参照する前に WebP へ変換または同期します。ファイルサイズは小さくしますが、圧縮しすぎてはいけません。タイトル、ラベル、数式、コード片、軸、指標値、矢印は、モバイルでも読める状態を保ちます。圧縮後にぼやけたり読みにくくなったりする場合は、より大きな WebP を残すか、画像を簡略化してから公開します。
レッスンを再構成するときは、先に明確な placeholder を置き、正式画像は最後にまとめて生成してもかまいません。placeholder でも、教育目的、対象ページ、画像の向き、三言語ファイル名セットを記録し、後の一括生成でスタイルと目的がずれないようにします。
一時的な placeholder と明確なフォローアップがない限り、1 つの言語だけに新しい画像を追加しません。正確な数値出力、数式、コード順序、指標値を扱う場合は、SVG または同じデータを固定した実験結果画像の三言語セットを優先します。
テンプレート感の強い SVG を置き換える
一部の古い SVG は正確ですが、色付きボックス、矢印、長い文章が並ぶスライドのように見えます。章の入口や大きな概念ページでは、より直感的な image2 PNG を優先します。
SVG を残す場面:
- 行列サイズ
- ベクトル幾何
- ターミナルパスとコマンド
- Python の評価順序
- 正確なデータ/表の形
image2 を優先する場面:
- Agent 実行ループ
- RAG アプリケーションループ
- 章レベルのロードマップ
- プロジェクトワークフロー
- 歴史的転換点
- Before / After 比較
画像を入れる順序
教材ページでは、できるだけこの順序にします。
- 先に画像を見る。
- 最小コードまたは操作を実行する。
- 出力や結果を見る。
- いま見た部分だけ説明する。
最小制作ループ
- 学習者の詰まりを見つける。
- 画像の意図を 1 文で決める。
- 教育目的に合わせて画像の向きと比率を選ぶ。
- placeholder を置く、または適切な種類の画像を三言語セットで生成/描く。
- 正式画像では、公開用のコース画像を WebP に変換または同期し、文字と重要な細部を読める状態に保つ。
- 英語、中国語、日本語ページに挿入し、対応する alt 文もそろえる。
- 画像が解決され、モバイルでも読め、サイトがビルドできることを確認する。
ページが空いているから画像を入れるのではありません。次の一歩が理解しやすくなるから入れます。