GitHub Docs でのビデオの使用

GitHub Docs のビデオについて

ビデオは、GitHub Docs ではほとんど使用されません。 記事に最適なユーザー エクスペリエンスを提供するためにビデオが必要な場合、書き込みテキストと共に使用されます。 ビデオは、書き込まれたコンテンツに代わるものではありません。 ビデオが唯一の情報伝達方法になることはありません。それは、情報を最新の状態に保つのが難しく、誰もがアクセスできるわけではないからです。

これらのガイドラインを使用して、ビデオを記事に含めるのが適切か、ドキュメントのランディング ページに含めるのが適切かを判断します。

ビデオへのリンクを追加する場合、または GitHub Docs にビデオを埋め込む場合は、github/docs リポジトリにある "GitHub Docs 内のビデオ" ファイルにビデオのメタデータを追加します。

Docs チームは、ビデオ コンテンツの作成または管理を行いません。 ビデオは重要な、または複雑なトピックを伝えるのを手助けするための純粋に補足的なものです。Docs チームが所有する種類のコンテンツではないので、慎重に使用する必要があります。

ビデオ チェックリスト

このチェックリストを使用すると、ビデオが記事またはランディング ページに追加するのに適しているかどうかを迅速に判断できます。

• 情報を伝える唯一の方法はビデオですか?
• GitHub ではビデオを所有していますか?
• ビデオはうまく制作されていますか? (詳しくは、「ベスト プラクティス」セクションを参照してください)。
• ビデオには、可能な限り広範なユーザー グループからのアクセスが可能ですか? (詳しくは、「アクセシビリティ要件」セクションを参照してください)。
• ビデオの長さは 5 分未満ですか?
• ドキュメント内でビデオには特定の対象ユーザーと目的がありますか? それが特定の製品または機能にのみ関連する場合は、バージョン管理を行う必要があります。 詳しくは、「バージョン管理」セクションをご覧ください。

これらの項目のいずれかに対して "いいえ" と答えた場合、ビデオは GitHub Docs に追加するのに適していません。

ビデオの管理

ビデオにメンテナンス スケジュールが設定されている場合、またはコンテンツが古くなった場合に監査および更新を直接担当するチームが用意されている場合は、追加の手順を行わずにビデオを含めることができます。

ビデオにメンテナンス スケジュールが設定されていない場合は、ビデオを確認または削除するのに適切なターゲット日に issue を作成します。

ベスト プラクティス

これらのベスト プラクティスを使用すれば、ビデオが適切に生成され、GitHub Docs に含めるのに十分な品質であるかどうかを容易に判断できます。

優れたビデオでは、ステップと目標を含む指導内容が紹介されているため、視聴している人は何を学習できるのかがすぐにわかります。 ビデオはデモンストレーション的なものであり、実行する関連の各手順を示し、説明します。 ビデオは魅力的で励みになるものにする必要があります。 GitHub Docs に含めるには、ビデオを適切に作成する必要があります。 適切に制作されたビデオには、障碍のある人に対する障壁がほとんどなく、プロのナレーションが用意され (ナレーション付きビデオの場合)、ビジュアルが鮮明であり、GitHub や Microsoft などの信頼できるソースから提供されています。

ビデオは、製品の概要、機能を示すビデオ、チュートリアルという 3 つのカテゴリに大別されています。 これらの説明は、各種ビデオの一般的な内容です。 一部のビデオは、1 つのカテゴリに完全には当てはまらない場合があります。しかし、正確なガイドラインを満たさなくても有用な場合があります。

製品の概要

• 目的: 製品の概要を簡単に説明し、主な機能を紹介し、ユーザーに興味を持ってもらいます
• 長さ: 1 分未満
• 想定される対象ユーザー: 機能が自分の目標達成に役立つかどうかを知りたい人、GitHub を初めて使用し、製品の機能を理解しようとしている人
• ドキュメント内の考えられる場所: ランディング ページとガイド

機能に関するビデオ

• 目的: 概念的または手続き型のコンテンツを補完します
• 長さ: 可能な限り短くし、5 分を超えないようにします。 長いコンテンツは複数の焦点を絞った短いビデオに分割します
• 想定される対象ユーザー: 機能についてまたはその使用方法を学習している人
• ドキュメント内の考えられる場所: ガイド、概念に関する記事、手順に関する記事

チュートリアル

• 目的: 初心者ユーザーが製品を使い始めるのを支援したり、導入を促進したり、複雑な機能を説明したりします
• 長さ: 個々のビデオは 5 分以下にする必要があります。 複雑なトピックの場合は、記事全体に一連の短いビデオを分散させることができます。 全体の長さは最大で 15 分とする必要があります
• 想定される対象ユーザー: 機能または製品の新規ユーザー
• 考えられる場所: ガイド

ビデオを使用する場合

誰かが画面間を移動する場合や、複数のメニューを介して進む必要のある機能をデモする場合など、動きまたは状態の変化を示すことが重要な場合は、ビデオを、スクリーンショットや図などの他のビジュアルの代わりに使用することがあります。 ただし、これらの手順を説明するには、スクリーンショットまたはテキストで十分な場合があります。

ビデオは、機能または製品を紹介するのにも役立ちます。複数の段落で記述する必要がある情報を、30 秒のビデオで補足できます。

ビデオを使用して、示されているプロシージャまたは概念の価値を説明します。

ビデオを使用しない場合

すぐに変更になる機能にはビデオを使用しないでください。ビデオが古くなってしまう可能性があります。 書き込まれたコンテンツと矛盾するビデオまたは、「スタイル ガイド」の一部に違反するビデオは使わないでください。 手順の説明や詳細を省略して、タスクを示すだけのビデオは使用しないでください。 ビデオは有用かつ関連性が高く、長期にわたって正確さを保つ必要があります。

アクセシビリティの要件

これらは、ビデオを GitHub Docs に含めるための最小要件です。 ビデオがこれらの要件のいずれかに違反している場合、それをドキュメントに追加することはできません。

• フラッシュまたはストロベ効果なし
• クローズド キャプションが必要です。 詳しくは、後の「ビデオ キャプションの作成」をご覧ください。
• キャプションが表示される場所とグラフィックスが重なっていない
• 文字体裁は読みやすいものでなければならない
• オーバーレイには十分なコントラスト比が必要
• テキストは、読み取れるのに十分な長さで画面上に表示される必要がある (テキストは、2 回声に出して読み上げるのにかかる時間よりも長く画面上に表示される必要がある)
• シーンごとに何が起こったかを説明するトランスクリプトを校正する必要がある。 詳しくは、後の「ビデオ トランスクリプトの作成」をご覧ください。
• ビデオが自動再生されない

ビデオ キャプションの作成

Docs サイトにビデオを追加するには、事前に人間が作成したキャプションを用意しておく必要があります。 自動キャプション テクノロジを使用すればキャプションを容易に作成できますが、正確さを期すためには人が校正および編集する必要があります。 ビデオ ホスティング サービスに YouTube などのネイティブ キャプション ツールが含まれている場合は、そのツールを使用してキャプションを準備したり、ビデオと一緒にアップロードする適切な形式の SRT または VTT トランスクリプト ファイルを作成したりできます。

キャプションの作成は、より多くの人がアクセスできるビデオを作成するプロセスの一部であるため、GitHub Docs に追加されるビデオの所有者はキャプションを提供する必要があります。

キャプションのガイドライン

可能であれば、キャプションはビデオ内で話されている言葉と正確に一致させる必要があります。 深刻な時間的制約により、所定の時間内にキャプションを読むことが難しい場合を除き、キャプションを言い換えたり切り詰めたりしないでください。

キャプションは、音声とほぼ同時に表示されるように同期させる必要があります。 キャプションは常に、話者が話し始めた瞬間に画面に表示されるようにタイミングを合わせる必要があります。 音声に正確に合わせてキャプションを読むのが難しいテンポの速いスピーチの場合は、スピーチが終了した後もキャプションを画面上に表示されるように拡張することができます。

ビデオに複数の話者が含まれている場合は、キャプションで話者を特定します。 これを行うには、話者の名前を追加するか、Developer などのわかりやすい名前を文の先頭に追加します。 (例: Jimmy: Hello.)。 これは、話者が変更されたときにのみ行う必要があります。すべての会話行に対して行うことが必要なわけではありません。 視覚的に誰が話しているのかが明らかな場合、話者を特定する必要はありません。

キャプションは 1 行または 2 行とし、1 行につき 32 文字以下にする必要があります。 新しい文はそれぞれ新しい行に置きます。 文の途中で改行する必要がある場合は、論理的な位置、たとえばコンマの後、あるいは and や but などの接続詞の前で改行してください。

YouTube でのキャプションの追加と編集

YouTube でホストされているビデオについては、YouTube のドキュメント「字幕を追加する」と「字幕を編集または削除する」を参照してください。

ビデオ トランスクリプトの作成

ドキュメントにリンクまたは埋め込まれたすべてのビデオについては、ビデオの説明的なトランスクリプトが必要です。 トランスクリプト記事は、YAML Frontmatter と Markdown コンテンツを使用して、他の記事と同様に書式設定されます。 Docs サイトにトランスクリプトを追加するには、content/video-transcripts で記事を作成し、トランスクリプトを記事の本文として含めます。 記事に、transcript-VIDEO-NAME.md のようなファイル名と、Transcript - VIDEO NAME の Frontmatter プロパティ title を指定します。 記事を video-transcripts ディレクトリの index.md ファイルに追加します。

トランスクリプト内で製品名などを置き換えるために、Liquid 変数や再利用可能変数を使用しないでください。 トランスクリプトはビデオ内の音声に忠実である必要があり、ビデオの作成後に変数を更新したり再利用したりした結果として、トランスクリプト内のテキストが変更されてはなりません。

トランスクリプトの作成は、より多くの人がアクセスできるビデオを作成するプロセスの一部であるため、ドキュメント サイトに追加されるビデオの所有者は、トランスクリプトのコンテンツを提供する必要があります。

トランスクリプトの基礎としてキャプションを使用できます。 キャプションを編集してタイムスタンプを削除し、以下で詳しく説明する関連情報を含めます。 説明トランスクリプトには、ビデオのコンテンツを理解するのに必要な音声および視覚の両方に関する情報のテキスト バージョンが含まれます。

• ビデオに複数の話者が参加している場合は、トランスクリプトで話者を特定します。
• 話者の性別がわかっている場合は、話者のアクションを説明するときに優先する代名詞を使用できます。 たとえば、She points to the computer screen. 話者の性別が不明であるか、説明されているビジュアルとは無関係な場合は、単数形の代名詞を使用できます。
• トランスクリプトは、論理的な段落、リスト、セクションで書式設定します。 それがユーザーがコンテンツを理解するのに役立つ場合は、セクションにヘッダーを追加できます。 ビデオを表示しないユーザーがいる場合に、彼らがトランスクリプトから情報を取得する方法を検討してください。
• 画面上のテキスト、関連する視覚要素、またはキャプションに含まれないスピーチ以外のサウンドを追加します。 これらの説明は、ビデオに付属する音声テキストの後に配置します。 視覚的な情報の書式を角かっこで囲みます。 たとえば、[Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.] のようにします。
• product_video プロパティをトランスクリプト記事の YAML Frontmatter に追加します。 product_video プロパティの値は、ビデオの YouTube URL です。 ビデオの YouTube URL はトランスクリプト記事に外部リンクとして表示されます。
• トランスクリプトの最後に、End of transcript. を書き込み、パターン For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page). の使用についてビデオで説明されている製品のランディング ページへのリンクを付けます。

音声およびビジュアルの文字起こしについて詳しくは、W3C ドキュメントの「テキスト トランスクリプトとビジュアルの説明」を参照してください。

外部でホストされているビデオからのトランスクリプトへのリンク

ホストされているプラットフォーム上でビデオの説明にビデオのトランスクリプトを含んでいる記事へのリンクを追加します。 詳しくは、YouTube のドキュメント「動画の設定を編集する」を参照してください。

埋め込みビデオのトランスクリプトへのリンク

ビデオが埋め込まれたコンテンツでは、YAML Frontmatter の product_video プロパティの下に product_video_transcript プロパティを追加します。 product_video_transcript の値は、video-transcripts ディレクトリ内のトランスクリプト記事へのリンクです。

title: Example product landing page
product_video: 'https://www.youtube-nocookie.com/embed/URL'
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE

ビデオのタイトル

タイトルは説明的なものとし、コンテンツ モデルに関するページに記載のタイトルのガイドラインに従う必要があります。 詳しくは、「GitHub Docs の記事の内容」をご覧ください。

バージョン管理

ビデオが特定の GitHub 製品 (Free、Pro、Team、GitHub Enterprise Server、および GitHub Enterprise Cloud) にのみ関連する場合、ビデオはそれらの製品に合わせてバージョン管理する必要があります。 Liquid 条件ステートメントを使用して、ビデオを適切にバージョン管理します。 Liquid 条件付きバージョン管理は、コンテンツを最初に作成する際に追加することが必要な場合もあれば、機能更新または GitHub Enterprise リリースに対してコンテンツを更新する際に追加することが必要な場合もあります。 流動性の条件付きステートメントとバージョン管理について詳しくは、「バージョン管理に関するドキュメント」をご覧ください。

ビデオ ホスティング

ビデオは、GitHub が所有し、Docs チームにアクセス権を付与できる場所でホストされている必要があります。 ビデオでは、ユーザーを追跡することも、Cookie を使用することも行わないでください。 現在、GitHub のビデオは YouTube でホストされていて、次のようにしてドキュメントに追加されます: 埋め込み URL のドメインを https://www.youtube.com/VIDEO から https://www.youtube-nocookie.com/VIDEO に変更して、プライバシー強化モードを使用します。