GitHub Docs 用の図を作成する

このガイドでは、 GitHub Docsのダイアグラムを作成するタイミングと方法について説明します。

この記事で

GitHub Docs の図について

図では、図形、線、ラベルを使用して概念を視覚的に説明します。 図を使用して、 GitHub Docsのテキスト情報をサポートします。

ダイアグラムは情報を複雑にしませんが、情報を受け取って処理する別の方法を示します。 一部の人々は情報を読むよりも見せてもらいたいと考えています。 視覚的なダイアグラムを操作できず、テキストで情報を表示する必要がある人もいます。

ダイアグラムには多くの用途があります。 ダイアグラムでは、段落または記事全体を記述する必要がある概念の概要を提供できます。 他のユーザーがダイアグラムを表示し、追加情報の詳細を読むかどうかを決定できます。 ダイアグラムは、プロセス全体を一度に確認したり、ワークフロー内の特定のステップをマイクロレベルで理解したりすることで、システム レベルの意思決定にも使用できます。 ダイアグラムはコンテンツであり、すべてのコンテンツと同様に、ユーザーが最適な使用方法を決定する必要がある場合に注意深く考慮する必要があります。

ダイアグラムは創造力を必要とします。 使用する正確な図形に関係なく、ユーザーを支援する図のアイデアがある場合は、 GitHub Docsに適している可能性があります。 次の要件と推奨事項は、 GitHub Docsに含めることができる図を作成するのに役立ちます。

ダイアグラム チェックリスト

GitHub Docsに含まれるには、図が次の条件を満たしている必要があります。

  • このダイアグラムには、できるだけ多くのユーザーがアクセスできます。
    • ダイアグラムには明確な開始点があり、簡単に従うことができます。
    • ダイアグラムは、表示される記事の完全なテキストの説明が先行するか後に来るが、完全に視覚的な形式で伝達される情報はありません。
    • ダイアグラムには適切なコントラストがあります。
    • ダイアグラムには適切な代替テキストがあります。
    • ダイアグラムは、可能な限り読みやすい要素を用いて、明確かつ鮮明にする。
  • ダイアグラムには受け入れ基準があり、それらを満たしています。
    • ダイアグラムには対象ユーザーがいます。
    • ダイアグラムには適切な量の情報と密度があります。
  • ダイアグラムは視覚的に優れています。
    • ダイアグラムは、このコンテンツ モデルに記載されているスタイル セットに従います。
    • ダイアグラムには、理解しやすくナビゲートするのに十分な情報が含まれていますが、過度に装飾されたり、不必要に複雑になったりするわけではありません。

ダイアグラムの管理

ダイアグラムの作成者は、それを維持する責任があります。 ダイアグラムが古い場合は、ダイアグラムを削除、更新、または置き換えるのが GitHub Docs チームの裁量です。

ダイアグラムを使用しない場合

ダイアグラムはテキストに代わるものではありません。 それらは記事で書かれた情報を補完します。 混乱を招く記事を簡略化または修正しようとするダイアグラムを追加しないでください。 記事のテキストを書き直し、書き換えられたテキストをサポートする場合は図を追加することを検討してください。

ダイアグラムを使用する場合

図は、ユーザーを支援し、視覚的な装飾だけではなく、 GitHub Docs で使用できます。 ダイアグラムが役に立つかどうかを判断するには、次のような受け入れ基準が必要です。

  • このダイアグラムの対象ユーザーは誰ですか?
  • このダイアグラムの範囲は?
  • ダイアグラムは付随するテキストをどのように補完しますか?
  • ダイアグラムの有効性をどのように評価しますか?

ダイアグラムには、常に同じ情報を完全に伝えるテキストが添付されている必要があります。

ダイアグラムの受け入れ基準

ダイアグラムの受け入れ基準を作成するには、これらの質問に回答します。

このダイアグラムの対象ユーザーは誰ですか?

記事などのダイアグラムには、幅広い対象ユーザーや特定の対象ユーザーを含めることができます。 たとえば、図の対象ユーザーは、組織の GitHub Advanced Security、 GitHub Code Security、または GitHub Secret Protection の購入を検討しているユーザーや、学生が GitHub Education のアプリケーション プロセスのしくみを学習しているユーザーなどです。

このダイアグラムの範囲は?

ダイアグラムの情報が多いほど、作成と理解が困難になります。 すべてのダイアグラムには、作成をガイドし、その有効性を評価するための確立されたスコープが必要です。 たとえば、 GitHub を説明する図には、非常に大きなスコープがあります。 すべての GitHub の製品と機能に関する詳細情報に入った場合は混乱を招く可能性があるため、このスコープの図で広範な概要を提供することが期待されます。 これに対し、 GitHubホストランナーまたはセルフホステッド ランナーが用途に適しているかどうかを評価するのに役立つ図は、範囲がより狭いため、より具体的で微妙な情報に入る可能性があります。

このダイアグラムは付随するテキストをどのように補完しますか?

ダイアグラムは、近くにあるテキストに応じて異なる目的を果たすことができます。 システムのテキスト説明に続く複雑なシステムを示す図は、概念全体を理解するのに役立つシステムの視覚的な説明を提供できます。 他のユーザーが実行しようとしているタスクを示す手順の前のダイアグラムは、一部のユーザーがタスクを正常に完了する準備をするのに役立ちます。 ダイアグラムにはテキストを使用して実現する目的が必要であり、ダイアグラムが記事で情報を伝達する唯一の方法になることはありません。

ダイアグラムの有効性をどのように評価しますか?

対象ユーザーとスコープを考慮すると、ダイアグラムを効果的にするために説明する必要がある内容を正確に特定できる必要があります。 GitHub Docsに図を含める前に、他のユーザーにレビューを依頼し、スコープに適した詳細な量で、指定した対象ユーザーに予想される情報が説明されているかどうかを判断します。

使用するダイアグラムの種類の選択

さまざまな人が異なるダイアグラムを有益さ見い出し、良いダイアグラムを作成するには、科学と同じくらいの芸術があります。 次の一般的なガイドラインは、使用するダイアグラムの種類を選択するのに役立ちますが、特定の受け入れ基準に適した一意のダイアグラムを用意することもできます。

時間を説明するダイアグラム

何が起こるかを説明するダイアグラムを作成する場合は、次のいずれかの種類のダイアグラムを検討してください。

  • フローチャート: フローチャートは、プロセスのステップを示す場合に役立ちます。 この例では、四角形はプロセス内のステップを表し、ひし形はグラフが 2 つの可能なエンドポイントに分岐する決定ポイントを表します。

    プロセスのステップを四角形で表し、チャートが分岐する決定ポイントをひし形で表しているフローチャートの例。

  • ガント チャート: ガント チャートは、タスクの所要時間と重複時間を示す場合に便利です。 この例では、横軸に "Time" というラベルが付いています。青い四角形は 3 つの個別のタスクを表しています。 タスク 1 とタスク 2 が重複しています。つまり、タスクの少なくとも一部が同時に発生します。 タスク 3 は他のタスクと重複しません。つまり、最初の 2 つのタスクが完了した後に行われます。

    「時間」というラベルの横軸に 3 つのタスクが配置されているガント チャートの例。

  • 体験マップ: 体験マップは、時間の経過に伴う何かの状態を示す場合に役立ちます。 この例では、横軸には「時間」というラベルが付いており、縦軸には「観察または測定されたもの」というラベルが付いています。 青い点は、特定の時間に測定値をマークし、時間の経過と共に傾向を示すために線で接続されています。

    期間を通してイベントを観測または評価するために、2つの軸に線を引いたジャーニーマップの例。

配置を説明するダイアグラム

何がどこにあるかを説明するダイアグラムを作成する場合は、次のいずれかの種類のダイアグラムを検討してください。

  • ブロック図: ブロック図は、項目を他の項目内に配置することによって、どのように整理されているかを示す場合に役立ちます。 この例では、"カテゴリ" というラベルが付いた最大の四角形、"マップ トピック" というラベルが付いた四角形、"アーティクル" というラベルが付いた四角形を使用して、コンテンツを GitHub Docs で整理する方法を示します。

    カテゴリ内のマップ トピック内の記事を示す重複する正方形を含む GitHub Docs コンテンツ モデルのブロック図。

  • 概念マップ: 概念マップは、物事間の関係を示す場合に便利です。 ラベルの付いた線とラベルのない線が異なると、物事がどのように接続されているか、相互に影響を与えるかが示されます。 この例では、4 つの青い四角形は概念を表し、それらの間の線はそれらの間に異なる関係を示しています。

    A、B、C、D というラベルが付いた 4 つの青い四角形間の関係を示す概念マップの例。

  • 階層: 階層は、カテゴリとサブカテゴリの間の関係を表示する場合に便利です。 この例では、階層の 3 つのレベルが垂直方向に編成されています。

    メイン カテゴリの下に 2 つのレベルのサブカテゴリを示す階層の例。

コンテキストを説明するダイアグラム

ダイアグラムを作成して、何かが正しい理由を説明する場合は、次のいずれかの種類のダイアグラムを検討してください。

  • Continuum 図: Continuum 図は、線形スペクトル上のどこに落ちるかを示す場合に役立ちます。 この例では、青い四角形は、目的の項目が連続体のオプション 1 よりもオプション 2 に近い値であることを示しています。

    2 つのオプション間の連続体と連続体上の項目の位置を表す横軸を持つ連続体の例。

  • クアドラント図: クアドラント図は、2 つの軸間の関係と、両方の軸のどこにあるかを説明するのに役立ちます。 この例では、横軸の左側には「単に装飾的」、右側には「特定の受入基準を満たす」というラベルが付けられています。 縦軸の上部には「書かれたテキストを補完」が、下部には「情報が提示される唯一の方法」というラベルが記されています。 " GitHub Docsの図" というラベルが付いた青い四角形は、右上のクアドラントに"書き込まれたテキストの補完" と "特定の受け入れ条件を満たす" の重なりによって形成されます。これは、これら 2 つのプロパティがあることを意味します。

    2 つの軸で作成された 4 つのクアドラントと、右上のクアドラントに青い四角形を含むクアドラント図の例。

  • ベン図: ベン図は、共通の特徴やアイデアの重複を示す場合に便利です。 円は概念またはモノを表し、円が重なる領域はモノ間の共通の特徴を表します。 この例では、"Octopus" というラベルが付いた円と "Cat" というラベルが付いた円の重なる部分には、タコと猫を組み合わせた "Octocat" というラベルが付けられています。

    2 つの円が重なっているベン ダイアグラムの例: 一方に "Octopus"、もう一方には "Cat" とラベルが付けられています。 円の交差部分には "Octocat" というラベルが付けられています。

スタイルのガイドライン

次のルールに従って、 GitHub Docsのスタイルに合った図を作成します。

図形

図形は、ダイアグラム内のオブジェクトまたは概念を表します。

GitHub UI の要素 (オクティコン、メニュー、ボタンなど) を使用して、関連していて読みやすい図を作成できます。

カスタムダイアグラム図形の場合は、関連する意味にこれらの図形を使用します。

  • 四角形: モノ、オブジェクト、アイデア。
  • 四角形の積み重ね: 類似するものの倍数。
  • ひし形: 図の流れに従った意思決定。
  • 円、星、またはその他の図形: 四角形で表されるものとは異なる必要がある一意のもの。

図形の配置は意味を伝えることができます。

  • 別の図形内の図形: これはその一部です。
  • 他の図形を指す矢印がある図形: これがそれに至る。
  • 図形の下にインデントされた図形: これはその一種です。
  • 線を引いて図形同士を結びつけます。これがあれに関連しています。 線の太さは、太い線が強い接続を示し、点線は弱い接続を示すなど、さらなる意味を伝えることができます。
  • 別の図形と重なり合う図形: これは、それと同じです。

行数

線は、図内の図形間の関係を表します。

さまざまな種類の線を使用して、リレーションシップの追加の意味を伝えます。

  • 非方向線: 非方向線で接続された 2 つの青い四角形を関連付けます。
  • 矢印で終わる一方向の線: シーケンスを表示するか、オブジェクトをポイントします。

右端に矢印が付いた線で接続された 2 つの青い四角形。

  • 両側に矢印がある双方向の線: 往復を示します。

両端に矢印が付いた線で接続された 2 つの青い四角形。

  • 角かっこ: 階層構造を作成します。 一般に、Web ページ上を簡単に移動できるように、角かっこを垂直方向に整理します。 階層の各レベルをインデントします。

角かっこで接続された 3 つの四角形の垂直方向 (左) と水平方向 (右) の配置の違いを示す 2 つの例。

ラベル

ラベルは視覚的および言語的なマーカーです。 ラベルは 25 文字以下にする必要があります。 ラベルのコントラストを上げるには、テキストを四角形に配置します。 多くの場合、ダイアグラムの作成の最後にラベルを付ける方が簡単です。

キー

キーは、グラフのさまざまな要素を説明したり、リレーションシップを明示的に明確にしたりすることで、理解に役立ちます。 すべてのダイアグラムにキーが必要なわけではありません。

キーは、ダイアグラムにない新しい情報を導入できません。 キーは、過度に複雑なダイアグラムを修正することはできません。 キーには、ラベルが適切に付いていないオブジェクトやリレーションシップを定義しないでください。

キーは、図形、色、またはその他の視覚的要素を説明するために使用する必要があります。 キーには、引用やスケールと操作の説明を含めることもできます。 キーには、フロー チャートの開始位置などの命令を含めることができますが、ほとんどの命令はダイアグラムを紹介するテキストに含める必要があります。

色彩

ダイアグラムに色が必要な場合は、プライマー デザイン システムで定義されている色を使用します。 より多くの人がダイアグラムにアクセスできるようにするには、情報を伝える唯一の方法として色を使用することはできません。 たとえば、色を使用してリレーションシップを示す場合は、線またはその他のビジュアル要素を使用して同じ情報を伝達する必要もあります。

GitHub Docsの図に推奨される色は次のとおりです。

色16 進コード
黒#24292f
青#0969DA
グレー#57606a
グリーン#1a7f37
Purple#8250df
赤#cf222e

技術仕様

  • PNG ファイル形式
  • 静的画像のみ (GIF なし)
  • 250 KB 以下のファイル サイズ
  • わかりやすいファイル名 (例: merge-conflict-diagram.png ではなく diagram-02.png)

小さな解像度で表示するのが難しい図を作成する必要がある場合は、関連するリポジトリまたはその他の適切な場所に、より大きなバージョンのダイアグラムへのリンクを含めます。 例については、「アクション ランナー コントローラー」をご覧ください。

ダイアグラムを作成するためのツール

プライマー カラーやその他のアセットにアクセスできるように、ダイアグラムを使用するために推奨されるツールは Figma です。 ただし、必要に応じて別のプログラムを使用できます。 上のスタイル ガイドの図形規約に従い、プライマー デザイン システムで定義されている色を使用します。

アクセシビリティ

ダイアグラムには、適切なコントラストと代替テキストが必要です。

プライマー デザイン システムで定義されている色を使用する場合は、ダイアグラムのコントラストが適切である必要があります。 他の背景色に対するコントラストを確認するには、Color Contrast Analyzer を使用します。

ダイアグラムの外観と、それが記事に含まれる理由を説明するダイアグラムの代替テキストを記述します。 長すぎて役に立たなくなる可能性があるため、ダイアグラムが代替テキストで伝えるすべてを説明しないでください。 代替テキストの記述について詳しくは、「スタイル ガイド」をご覧ください。

ダイアグラム内のすべての情報は、図に付随するテキストでも伝える必要があります。

バージョン管理

一部の図は、すべての GitHub プラン (GitHub Free、 GitHub Pro、 GitHub Team、 GitHub Enterprise Cloud、および GitHub Enterprise Server) に適用されます。 この場合、バージョン管理は必要ありません。

図が GitHub Enterprise Serverの一部のプランまたはバージョンにのみ関連する場合、図は Liquid 条件ステートメントを使用してバージョン管理する必要があります。 コンテンツが最初に作成されたときにこのバージョン管理を追加する必要がある場合や、コンテンツが機能更新プログラムまたは GitHub Enterprise Server リリース用に更新されたときに追加する必要がある場合があります。

ダイアグラムが特定のバージョンにのみ関連し、すぐに古くなる可能性がある場合は、情報伝達をより効果的にするために、より簡単に保守できるオプションが適しているかを検討してください。

ソース管理

ダイアグラムは、assets/images/help/ リポジトリ内の docs ディレクトリ内の関連する ディレクトリに格納されます。 新しいダイアグラムを作成する場合は、適切なフォルダーに追加します。 既存のダイアグラムを更新する場合は、既存のダイアグラムを更新されたバージョンに置き換えます。

新しいダイアグラムを作成するときは、それを Docs Figma チームの Diagrams プロジェクトに追加するか、または Figma ファイルのコピーを Docs チームのメンバーに提供します。 別のプログラムでダイアグラムを作成する場合、このガイドの要件と推奨事項を満たしている場合は GitHub Docs に含めることができますが、古くなった場合は更新されるよりも削除される可能性がはるかに高くなります。

例

この図他の四角形内の四角形を効果的に使用して、クラウドに含まれるコードスペースの部分を視覚的に説明し、矢印を使用して、クラウドでホストされているコードスペースとローカル エディターの間の関係を示します。

Azure 仮想マシンで実行されているコード エディターと codespace の間の関係を示す図。