画像、メディア、資産の追加方法

共有資産のメディアを格納して使用する

画像やメディアを追加する前に（特に、メディアコンテンツが二次的な技術をデモする場合）、 mdn/shared-assets リポジトリーにすでに存在するものを使用できるかどうか調べます。 このリポジトリーを、ストレージ、展開、ライセンスを心配することなく、例えば適切なリソースを選択するために参照できるメディアライブラリーとして扱います。

リポジトリーには、音声、映像、フォント、写真、図表、アイコンなどの画像、PDF、字幕ファイル、色プロファイルなどの各種ファイルが含まれます。 リポジトリーに適当なものがなければ、追加したいメディアのソースファイルとともにリソースを追加することができます。 例は、共有資産のための HTTP ディレクトリーにあります。

MDN ページで shared-assets リポジトリー内の何かを使用するには、プロジェクト README の Using shared assets in documentation の節を参照してください。

ベクター形式の使用

一般的に、画像、特に図表を追加する場合は、次の理由から、 SVG のようなベクター形式を使用することを検討してください。

• 任意の統合開発環境 (IDE) やオンラインツールを使用して、開発者が SVG を直接編集することができます。 .png の編集には通常、ゼロから資産を再作成するか、画像編集ソフトウェアを使用する必要があるため、エラーの可能性があり、視覚的または圧縮アーティファクトが発生する可能性があります。
• SVG は Git で差分が取れます。一方、ファイル全体が変更されるとバイナリーでの変更として差分が比較されるため、変更された .png ファイルが 1MB の場合、マージコミットのたびにリポジトリーサイズが1MB増加します。
• 柔軟な UX。 SVG はベクター形式なので、どんなに拡大してもぼやけることはありません。

コンテンツリポジトリーへの画像のコミット

shared-assets リポジトリーが用途に適していない場合は、画像を content （en-USの場合、または translated-content）リポジトリーに追加することができます。 文書に画像を追加するには、文書のフォルダーに画像ファイルを追加し、文書の index.md ファイルで Markdown の画像構文（英語） または HTML の <img> 要素を使用して画像を参照してください。

例を通して説明しましょう。

1. まず、 mdn リモートの main ブランチから、最新の内容を含む新しい作業用ブランチを作成しましょう。

   bash

   cd ~/path/to/mdn/content
   git checkout main
   git pull mdn main
   # "yarn" を実行して、 yarn が最新の状態であることを確認する
   git checkout -b my-images
   

2. 文書フォルダー内に自分の画像を追加してください。この例では、 files/en-us/web/css の記事に新しい画像を追加することを想定してください。

   bash

   cd ~/path/to/mdn/content
   cp ../some/path/my-cool-image.png files/en-us/web/css/
   

3. 各画像に対して filecheck を実行すると、何か問題があった場合にメッセージが表示されるかもしれません。 詳しくは、画像の圧縮の節を参照してください。

   bash

   yarn filecheck files/en-us/web/css/my-cool-image.png
   

4. 文書内で画像用の Markdown 構文を使って画像を参照し、画像を記述する括弧の間に alt 属性用の説明テキストを記述するか、 alt 属性を持つ <img> 要素を files/en-us/web/css/index.md 内に記述してください。

   md

   ![My cool image](my-cool-image.png)
   <img src="my-cool-image.png" alt="My cool image" />
   

5. 削除・作成・変更したファイルをすべて追加してコミットし、さらにブランチをフォークにプッシュしてください。

   bash

   git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html
   git commit
   git push -u origin my-images
   

6. これでプルリクエストを作成する準備ができました。

画像に代替テキストを追加

すべての画像、![] および <img> には、alt テキストを記載する必要があります。 alt 属性は短く、画像が伝えるすべての関連情報を提供する必要があります。 画像の説明文を書くときは、その画像の価値ある情報と、ページのコンテンツは読めても画像を読み込めない人にその情報をどう伝えるかを考えてください。

画像の代替テキストは、その文脈に基づいたものにしましょう。 犬のフラッフィーの写真が、Yuckymeat ドッグフードのレビューの横にいるアバターであれば、alt="Fluffy" が適切です。 同じ写真が動物保護団体の里親募集ページの一部である場合、画像から伝わる情報は、犬の親になる見込みのある人に関連するものです。例えば、alt="フラッフィー、テニスボールを咥えた、とても毛の短い三毛のテリア。" のようにします。 周囲のテキストには、フラッフィーの大きさや犬種が記載されている可能性が高いので、それを含めると冗長になってしまいます。 画像を詳細に記述するのは控えましょう。親になる見込みのある人は、犬が屋内か屋外か、赤い首輪と青いリードを持っているかなどは知る必要がありません。

スクリーンショットの場合は、画像から何を知ったかを書き、スクリーンショットの内容は詳しく書かず、読者が必要としない、あるいはすでに知っている情報を除外しましょう。 例えば、Bing の設定変更についてのページで、Bing の検索結果のスクリーンショットがある場合、検索語や検索結果の数などはこの画像のポイントではないので記載しないようにしましょう。 alt は、Bing で設定を変更する方法という、その時点でのトピックに限定してください。 alt は、alt="設定アイコンは、検索フィールドの下記ナビゲーションバーにあります。" のようにします。 スクリーンショットであることをユーザーが知る必要はなく、 Bing の設定変更を説明するページにいるため、すでに Bing であることを知っているため、「スクリーンショット」や「Bing」を記載しないでください。

Markdown と HTML での構文は以下の通りです。

![<代替テキスト>](<画像の URL>)
<img alt="<代替テキスト>" src="<画像の URL>">

例えば次のようにします。

![OpenWebDocs のロゴ: 本の虫のカール](carle.png)
<img alt="OpenWebDocs のロゴ: 本の虫のカール" src="carle.png" />

純粋に装飾的な画像は空の alt を設定すべきですが、 MDN ドキュメント内の画像には何らかの目的があるはずなので、空ではない文字列の記述が必要です。 代替テキストに関するヒントについては、 An alt Decision Tree を参照して、さまざまな状況で画像に alt 属性を使用する方法を学んでください。

画像の圧縮

MDN Web Docs のページに画像を追加する場合、読者のためにダウンロードサイズを節約するために、（品質を落とさずに）可能な限り圧縮されていることを確認する必要があります。 実際、これを行わないと CI プロセスが失敗し、ビルド結果で画像の一部が大きすぎるという警告が表示されます。

画像を圧縮するのに最適な方法は、内蔵の圧縮ツールを使用することです。 filecheck コマンドに --save-compression オプションを使用すると、画像を適切に圧縮することができます。 このオプションは画像を可能な限り圧縮し、元画像を圧縮後の画像に置き換えます。 例えば、次のようにします。

yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression

動画を MDN ページへ追加

MDN Web Docs は動画が多いサイトではありませんが、動画コンテンツを記事の一部として使用することに意味がある場所がいくつかあります。 この記事では、 MDN の記事に動画を含めることが適切な場合について説明し、シンプルだが効果的な動画を予算内で作成するためのヒントを提供します。

技術文書、特に参考資料や上級レベルガイドに動画コンテンツを使用することには、いくつかの反対意見があります。その中には次のようなものがあります。

• 動画は直線的です。 人々はオンラインドキュメントを最初から最後まで直線的に読む訳ではありません。 彼らは探すのです。 動画は本当に探しにくいので、ユーザーは最初から最後までコンテンツを見ることを強いられます。
• 動画はテキストよりも情報密度が低い。 何かを説明する動画を視聴するのは、同等の説明書を読むよりも時間がかかります。
• 動画はファイルサイズが大きいので、テキストよりもコストがかかり、パフォーマンスも低い。
• 動画にはアクセシビリティの問題があります。一般にテキストよりも制作費がかかりますが、特にローカライズやスクリーンリーダーの利用者が使えるようにするのが大変です。
• 最後の点に加えて、動画は、テキストコンテンツよりも編集・更新・保守がはるかに困難です。

多くの人気の動画サイトがあり、多くの動画チュートリアルを提供しています。 MDN は動画主体のサイトではありませんが、動画は特定の文脈で MDN に登場することがあります。

私たちが最もよく使うのは、言葉で簡潔に説明するのが難しい、ある種の指示シーケンスや複数ステップのワークフローを説明するときです。「こうして、ああして、こうなる」。 特に、複数のアプリケーションやウィンドウにまたがるプロセスや、簡単には説明できないような GUI 操作を記述する場合に便利です。「左上のアヒルのようなボタンをクリックしてください。」

このような場合、「何を意味しているのか」を見せる方が効果的なことが多いのです。

動画コンテンツのガイドライン

MDN 用の動画は以下のようにあるべきです。

• 短い。 30 秒以下、できれば 20 秒以下の動画にするようにしましょう。 これは、人々の注意力に大きな負担をかけない程度の短さです。
• シンプル。ワークフローはシンプルに、 2 ～ 4 つの明確なピースを作るようにしましょう。 そうすることで、よりわかりやすくなります。
• 無音。音声は動画をより魅力的にしますが、作るのにずっと時間がかかります。 また、何をやっているのか説明しなければならないので、動画が長くなり、ローカライズのコストが（金銭的にも時間的にも）かさみます。

もっと複雑なことを説明する場合は、短い動画とスクリーンショットを組み合わせて、テキストを挟むとよいでしょう。 テキストは、動画で説明した内容を補強するのに役立ち、ユーザーはテキストと動画のどちらを頼りにしてもかまいません。 良い例として、アニメーションインスペクターの使い方を参照してください。

さらに、以下のことを考慮してください。

• 動画は、埋め込み前に YouTube にアップロードしてください。 この用途では、アスペクト比は 16:9 を推奨します。そうすれば、表示フレーム全体が埋まり、動画の上下（または左右）に醜い黒帯が発生することはありません。 そのため、例えば 1024×576、1152×648、1280×720 の解像度を選択するとよいでしょう。
• アップロード時に見栄えが良くなるように、動画は HD で録画してください。
• DevTools の動画では、ページのコンテンツとは対照的なテーマを選択することをお勧めします、例えば、例のウェブページが明るいテーマであれば、暗いテーマを選択してください。 それは、何が起こっているのか、どこで DevTools が始まり、ページが終了するのかを容易に理解することができます。
• DevTools の動画では、見せたいものをすべて見せながら、 DevTools をできるだけ拡大し、問題なく見えるようにしてください。
• デモしようとしているものがマウスカーソルで覆い隠されていないことを確認してください。
• 画面録画ツールで、マウスクリックの視覚的なインジケーターを表示するように設定することが有用であるかどうかを検討してください。

動画ツールとソフトウェア

動画を録画するためには、何らかのツールが必要です。 無料のものから高価なものまで、またシンプルなものから複雑なものまで、さまざまなものがあります。 もし、すでに動画コンテンツ制作の経験があるのなら、それは素晴らしいことです。 そうでない場合は、簡単なツールから始めて、動画制作が楽しくなり、より興味深い作品を作りたくなったら、より複雑なものに手を出すことをお勧めします。

次の表は、良いスターターツールのお勧めをいくつか示しています。

QuickTime Player のコツ

macOS をお使いの場合は、 QuickTime Player が利用できるはずです。 実はこれもかなり簡単な簡易録画機能を備えています。

1. メインメニューから ファイル > 新規画面録画 を選択します。
2. 画面録画 ボックスで、録画ボタン（赤い丸いボタン）を押す。
3. 録画したい画面の領域を矩形でドラッグします。
4. 録画開始 ボタンを押します。
5. 録画したい動作をする。
6. 停止 ボタンを押す。
7. メインメニューからFile > Export As... > 1080p を選択し、 Hi Definition として保存します。

その他のリソース

• How to Add Custom Callouts to Screencast Videos in ScreenFlow

動画を作成するためのワークフロー

以下の節では、動画を作成して MDN ページに表示させるための一般的な手順を説明します。

まず、撮影したい流れを計画します。開始と終了の最適なポイントを検討します。 デスクトップの背景とブラウザーのプロファイルがきれいであることを確認します。 特に複数のウィンドウを使用する場合は、ブラウザーのウィンドウの大きさと配置を計画します。

実際に録画する内容を綿密に計画し、録画する前に何度か手順を練習してください。

• 手順の途中で動画を開始するようにしないでください。視聴者が操作を理解するのに十分な文脈を持っているかどうかを考慮してください。 例えば、短い DevTools の動画では、 DevTools を開くところから始めて、視聴者が方向感覚を掴めるようにするのがよい考えです。

• 操作の内容を考え、スピードを落とし、明確にしてください。 ある動作（例えば、アイコンをクリックする）をしなければならないときは、ゆっくり明確に操作してください。例えば、

  • マウスをアイコンの上に移動させる
  • 強調またはズーム（常にではなく、必要性を感じるかどうかによる）
  • 一旦停止する
  • アイコンをクリックする

• UI を表示する部分のズームレベルを計画します。 すべての人が高解像度で動画を見ることができるわけではありません。 後処理で特定の部分をズームすることができますが、事前にアプリをズームするのも良い考えです。

録画

見せたいワークフローを録音するときは、スムーズかつ着実に流れを進めてください。 ボタンをクリックするなど、重要な場面では 1 〜 2 秒の間、一時停止してください。 マウスポインターが、デモを行う上で重要なアイコンやテキストを隠してしまわないように注意してください。

最後に 1 ～ 2 秒の間を置いて、流れの結果を示すことを忘れないでください。

後処理

後処理では、重要な瞬間を強調することができます。 ハイライトはいくつかの要素で構成されており、それらを組み合わせて使うことが多いでしょう。

• 画面の一部を拡大する。
• 背景をフェードさせる。

ワークフローの重要な瞬間、特に詳細が見えにくい部分を強調します。例えば、特定のアイコンをクリックする、特定の URL を入力するなどです。 ハイライトは 1 〜 2 秒を目安に。 ハイライトの最初と最後に、短いトランジション（200 ～ 300 ミリ秒）を追加するとよいでしょう。

ズームイン、ズームアウトの連続では、視聴者が船酔いしてしまいますので、ほどほどに。 必要であれば、動画を希望するアスペクト比に切り抜いてください。

アップロードと動画の埋め込み

現在 MDN で動画を表示するには YouTube にアップロードする必要があります。例えば mozhacks チャンネルなどです。 もし適切な場所がなければ、 MDN スタッフにアップロードを依頼してください。

埋め込み

アップロードした動画は、 EmbedYouTube というマクロを使って、ページ内に埋め込むことができます。 これは、ページ内の動画を表示させたい位置に以下のように挿入することで使用します。

{{EmbedYouTube("you-tube-url-slug")}}

マクロ呼び出しで取るプロパティは、 URL 全体ではなく、動画の URL の末尾にある文字の列です。 例えば、動画の URL が https://www.youtube.com/watch?v=ELS2OOUvxIw であれば、必要なマクロ呼び出しは次のようになります。

{{EmbedYouTube("ELS2OOUvxIw")}}

関連情報

• Using SVG format instead of .png images (MDN GitHub discussion)