スタイル ガイド

GitHub のドキュメントが一貫性を保ち、読者にとってわかりやすい明確なパターンに沿うように、このガイドに従ってください。

この記事の内容

Note

このガイドラインは、GitHub のドキュメント専用です。 ここで説明していないトピックに関する、スタイルについての一般的な質問やガイダンスについては、Microsoft スタイル ガイドをご覧ください。 docs.github.com のソース コンテンツに固有のマークアップについては、「GitHub Docs での Markdown と Liquid の使用」を参照してください。 GitHub ブランドに関する質問については、GitHub ブランド ガイドを参照してください。

GitHub Docs でのスタイルのアプローチ

  • GitHub のスタイル ガイドは、シンプルであることを目指しています。 幅広いシナリオに簡単に適用できるガイドラインであると考えています。
  • 文法やスタイル ガイドに従って正しいか間違っているかという判断ではなく、ユーザーにとって何が一番良いのかという判断を下しています。 一貫性を維持しながら、変化に対しても柔軟かつ寛容に対応しています。
  • チームやドキュメント セットの拡大に合わせてスタイル ガイドの範囲を調整するとともに、ユーザーにとって役立つ高品質で有意義な内容を生み出すために、GitHub では、スタイルについてのあらゆる質問を包括的に取り上げようとするのではなく、影響が大きく価値が高いシナリオに焦点を当てています。
  • 一貫性があり文法的に正確であることは重要ですが、わかりやすさと意味はさらに重要です。
  • スタイルや構造を決めるときは、コンテンツのユニット内に含まれている情報とその情報のコンテキストを考慮しています。
  • ヘルプ ドキュメントに特有の質問がスタイル ガイドで取り上げられていない場合、これらの原則を使って判断しています。 レビュー担当者から質問を受けた場合は、その判断について説明します。

監査ログのイベント

個人用、Organization、Enterprise など、アカウントの種類ごとに監査ログに表示される可能性のある各イベントを文書化します。

監査ログ イベントの説明を記述するときは、過去の時制と受動態を使用して、すべてのバージョンに適用されるように、発生したイベントを説明してください。 "誰々がトリガーした" など、記事のコンテキストで既に暗黙的に示されている語句で文を始めないでください。

  • 使用: リポジトリの可視性が変更されました。
  • 使用: すべての新しいリポジトリでシークレット スキャンが有効になりました。
  • 避ける: Organization オーナーが、Organization の 2 要素認証の要件を無効にしました。
  • 避ける: codespace がアクセスできるリポジトリをユーザーが更新したときにトリガーされました。

警告

アラートは、特に重要な記事内の情報を強調し、情報の流れが途切れないようにします。

アラートを慎重に使用します。 連続してアラートを使用したり、1 セクションに複数のアラートを使用したりしないでください。

アラートは簡潔にする必要があります。 情報が複数の文で構成されている場合、または順序付けされたリストまたは順序なしリストが必要な場合は、代わりにセクション見出しの下に情報を配置することを検討してください。

アラートのタイプ

4 種類のアラート (注意: ヒント、警告、および注意) を使用します。

注意

ユーザーが考慮する必要がある可能性がある追加のコンテキストを提供します。 タスクは注意のアラートにある情報なしで実行できますが、一部のユーザーは一部のコンテキストで注意の恩恵を受ける可能性があります。

注意は、記述されているプロセスの中心ではなくカッコ内に入れるような次のような情報を伝達する場合に特に役立ちます。

  • 特定のユーザー設定など、プロセスの結果に影響する可能性がある注意事項。
  • ベータ や 非推奨 など、可用性の変更の対象となる製品と機能。

たとえば、「シークレット スキャンからのアラートの評価」では、注意を使って、GitHub トークンのメタデータが現在 ベータ 段階であることをユーザーに知らせています。

Note

現在、GitHub トークンのメタデータは ベータ 段階であり、変更される可能性があります。

ヒント

おすすめ、ベスト プラクティス、または製品ヒント。 ヒントには、ユーザーが自分の判断で従うことができる必須ではない情報が含まれています。 新しいユーザーを対象とした記事で特に便利です。

たとえば、「プロフィールをパーソナライズする」では、organization に対して @mention を行うときに想定すべきことをユーザーが理解できるように、ヒント アラートを使っています。

Tip

Organization に対して @mention を行うと、自分がメンバーであるものだけがオートコンプリートされます。 以前の職場など、自分がメンバーではない Organization に @mention することもできますが、その Organization の名前はオートコンプリートされません。

警告

タスクを開始または続行する前にユーザーが認識する必要がある潜在的なリスクを強調表示します。

警告アラートは、コマンド ラインや API など、GitHub UI の外部で発生するプロセスに特に関連します。

たとえば、「SSH認証局について」にはコマンド ラインの手順が記載されており、警告アラートを使って、一度発行された証明書は取り消すことができないことをユーザーに通知しています。

Warning

証明書が署名されて発行されると、その証明書を取り消すことはできません。 必ず -V フラグを使用して、証明書の有効期間を設定してください。そうしないと、その証明書は無期限に使用できることになります。

注意事項

特にセキュリティ リスクやデータ損失の可能性がある場合は、実行する前に細心の注意が必要な危険または破壊的なアクションをユーザーに警告します。

注意のアラートは、通常、コマンド ラインや API など、GitHub UI の外部で発生するプロセスを記述する場合にのみ必要です。

アラートの書式設定

ドキュメント セットには、さまざまな種類のアラートに標準の書式設定と色を使っています。

アラートは Markdown を使用してレンダリングされます。

注意：

> [!NOTE]
> Keep this in mind.

ヒント:

> [!TIP]
> Here's a suggestion.

警告:

> [!WARNING]
> Be careful.

注意:

> [!CAUTION]
> Be extremely careful.

アラートの Liquid 構文は引き続きサポートされており、古い記事で表示されることもありますが、新しいアラートには使用しないでください。

アラートの書式設定の詳細については、「GitHub Docs での Markdown と Liquid の使用」の「アラート」を参照してください。

ボタン

ランディング ページと一部の記事にはボタンがあり、これを使うと、ユーザーは、他の記事や他の GitHub Web ページの関連コンテンツに移動します。 ボタンは、説明されているタスクを完了するには別のページに移動する必要がある場合に使います。 たとえば、「GitHub Enterprise Cloud のトライアルを設定する」には、試用版のサインアップ ページに移動するためのボタンがあります。試用版を設定するプロセスでは、ここで次の手順を実行するからです。 「移行に関するドキュメント」のランディング ページでは、移行を始めるときにほとんどのユーザーが読んでおく必要がある記事に誘導するボタンを使っています。

ボタンを使ってユーザーが GitHub Docs サイトから離れるように促す場合は、行動喚起 (CTA) ボタンのガイドラインに従ってください。 ランディング ページまたは記事に別の種類のボタンを含める場合は、GitHub Docs チームから承認を得る必要があります。

行動喚起 (CTA) ボタン

CTA ボタンを使うと、記事を読み終わった後、または記事で説明されているタスクの実行の一環として、ユーザーに移動してほしいリンク先やユーザーに移動を勧めるリンク先が強調表示されます。 CTA を使った誘導先は、GitHub 所有のドメインのみとする必要があります。 たとえば、「GitHub Copilot を使用して IDE でコードの提案を取得する」の「GitHub Copilot を試す」の CTA は、GitHub.com の GitHub Copilot 設定メニューにリンクされています。

CTA ボタンは、リンクへの移動がユーザーのニーズに対応している場合にのみ含めてください。 CTA ボタンを、GitHub の機能や製品のマーケティングのみを目的として使わないでください。 上記の例では、GitHub Copilot を試したいユーザーは、Copilot 設定メニューに移動する必要がありますが、記事を読み終わった後に移動したいと思うかもしれません。 反対に、コードの記述とそのための pull request の作成の一環としてユーザーが Copilot を使うとしても、Copilot は "pull request を作成する" というユーザーのニーズにつながっていないため、GitHub では、[Try GitHub Copilot] という CTA を「pull request の作成」に追加していません。 ほとんどのユーザーは、Copilot を使わずに pull request を作成します。 ただし、Copilot の概要についての記事を読んでいるユーザーは、Copilot をまだ使っていないならば試してみたいと思うかもしれません。 そのため、アクセスしようとしている場所にユーザーが移動できるように、この CTA ボタンを追加しています。

次の書式を使って CTA のスタイルを設定します。

<a href="https://github.com/DESTINATION/URL?ref_cta=CTA+NAME&ref_loc=LOCATION&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Try PRODUCT NAME</span> {% octicon "link-external" height:16 %}</a>

プレースホルダーをCTA の関連情報に置き換えます。

  • DESTINATION/URL: ボタンが移動する先の URL。
  • CTA+NAME: CTA の名前。 たとえば、GHEC+trial または Copilot+Business+Trial です。
  • LOCATION: CTA の GitHub Docs 内の場所。 たとえば、Setting+up+a+trial+of+GitHub+Enterprise+Cloud のようにします。

コード

コード ブロック

読者がコード ブロック内を横方向にスクロールする必要がないように、コード サンプルは 1 行あたり約 60 文字に抑えてください。 コード ブロック内でコメントを使うのではなく、コード ブロックの前に説明テキストを配置してください。 コード ブロックの構文と書式設定の詳細については、「GitHub Docs での Markdown と Liquid の使用」を参照してください。

コード ブロック内では、次のようにしてください。

  • 最初のコード フェンスの後に、サンプルの言語を指定します。 サポートされているすべての言語一覧については、github/docs リポジトリのコード言語に関するページを参照してください。

  • HTML を使用してCODE ブロックのスタイル設定やマークアップを行わないでください。

  • 参加者が置換する必要があるプレースホルダーは、すべて大文字で独自の VALUE にスタイルを設定します。

    • 以下を使います: git checkout -b BRANCH-NAME
    • 以下は使いません: git checkout -b <branch-name>

  • コマンド自体の前のように $ コマンド プロンプトを使用しないでください。 これらのプロンプトにより、リーダーがコマンドをコピーして貼り付けるのが困難になります。

    • コマンドとコマンドの出力を表示する場合は、例の出力をコメント アウトします。

    • 以下を使用してください。

      command
# output

    • 以下は使いません:

      $ command
output

  • コード例に { or } が含まれており、これを表示する必要がある場合は、そのセクションを {% raw %} {% endraw %} にラップして、そのセクションに対する Liquid 処理を無効にします。

    • 以下を使用してください。

      GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}

    • 以下は使いません:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  • コード例に解析が必要な内容が含まれている場合は、そのセクションの内容をエスケープするのではなく、解析するためにそのセクションを <pre> </pre> タグで折り返します。

コマンド

短いコマンド名を参照するには、インライン コード ブロックを使います。

  • 以下を使います: 実行中のクラスターの状態を確認するには、ghe-cluster-status コマンドを使います。

長いコマンドや複雑なコマンドには、コマンド ブロックを使います。

  • 以下を使います: 任意のクラスター ノードの管理シェルに接続するとともに次を実行することで、スケジュールされた期間に従ってメンテナンス モードを有効にします。

    ghe-cluster-maintenance -s

次のような $コマンド プロンプトは含めないでください。 コマンド名にはインライン リンクを使わないでください。

出力

コマンドの出力を表示する場合は、例の出力をコメント アウトして、ユーザーがコマンドをコピーして貼り付け、変更せずに実行できるようにします。

  • 以下を使用してください。

    git lfs install
# Git LFS initialized.

  • 以下は使いません:

    $ git lfs install
> Git LFS initialized.

例

コード例で大きなファイルを参照する場合は、コンテキスト内で独自のコードを編集する方法をユーザーが理解できるように、そのファイルの関連するセクションを表示します。

  • 以下を使用してください。
on:
  schedule:
    - cron:  "40 19 * * *"
  • 以下は使いません:
schedule:
  - cron:  "40 19 * * *"

ファイル名とディレクトリ名

バックティックスを使用して、ファイル名とディレクトリ名への参照をモノスペース フォントで書式設定します。 全般的にファイルの種類が、すべて大文字の README ファイルのように、特定の大文字と小文字の規則に従っている場合は、定着している規則を使います。

  • 以下を使います: README.md ファイルに、リポジトリに関する情報を追加します。
  • 以下を使います: .github/workflows/ ディレクトリに example-workflow.yml ファイルを作成します。
  • 以下は使いません: .github/workflows/ ディレクトリに example-workflow.yml ファイルを作成します。
  • 以下は使いません: example.js ファイルを削除します。

[インデント幅]

アクション ファイルやワークフロー ファイルなどの YAML の例では、2 つのスペースを使って、入れ子になったリストとブロック シーケンス内の行をインデントします。

  • 以下を使用してください。
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

Reusables をインデントするには、data/reusables/README.md をご覧ください。

スケジュールされたワークフロー

一度に実行されるワークフローが多すぎる場合は、ワークフローの実行が遅れます。 多くのユーザーが GitHub Docs からコードをコピーするため、GitHub では、ユーザーが混雑時を避けるように促す例を使う必要性が生じています。

  • 最も混雑している時間が 1 時間に実行される例は使用しないでください。
  • 必要以上に頻繁に実行する例は使わないでください。 たとえば、その例が、5 分ごとに実行しなくても、30 分ごとに実行すれば意味を成すかどうかについて検討してください。
  • 例ごとに異なる時間帯を使ってください。

強調

文章の単語や一部を強調するには、太字を使用します。 強調を控えめに使用し (連続する単語は 5 語以内)、視覚的に読みやすくするための補助として使用することを心がけてください。

  • すべて大文字のプレースホルダー テキストなど、他の書式設定が適用されている単語を強調する場合は太字を使用しないでください。
  • アクセシビリティのために、意味や強調を伝える唯一の方法として太字を使用しないでください。

次に例を示します。

  • 使用: マネージド ユーザー アカウント パブリック コンテンツを作成したり社外で共同作業したりすることはできません。
  • 以下は使いません: [タイトル] の横に、新しいキーの説明ラベルを追加します。

エラー メッセージ

GitHub 製品またはインターフェイスからのエラー メッセージのテキストを記事に含める場合は、メッセージが表示されたインターフェイスに従ってテキストを書式設定してください。

  • メッセージが GitHub の Web インターフェイス、または GitHub Desktop や GitHub Mobile などのグラフィカル クライアント アプリに表示される場合は、メッセージを UI 内の他のテキストと同様に扱います。 詳細については、「ユーザー インターフェイスのテキスト」を参照してください。

  • メッセージがコマンド ライン インターフェイス、ログ出力、または API からの応答に表示される場合は、テキストを正確に再現し、バックティックを使用して、固定スペース フォントを使用したメッセージの書式設定を行います。

期限切れになるコンテンツ

一般に、期限切れになるコンテンツは文書化しないでください。 GitHub Docs にアクセスするユーザーは、情報が正確で最新であることを確信するはずです。

期限切れになることがわかっているコンテンツを文書化する必要がある場合は、コンテンツ リンターを使用して、コンテンツ満了日にタグを付けて追跡できます。 これにより、コンテンツに古いフラグが設定され、コンテンツ自体以外の満了日の追跡が回避されます。 期限切れのコンテンツ タグを書式設定する方法については、「コンテンツ リンターの使用」を参照してください。

脚注

脚注はできるだけ使わないでください。 代わりに、アラートを使ったり、別の情報で情報を示したりすることができないかどうかを検討してください。 NICE.org.uk で紹介されている脚注の代替手段の例の一部をご覧ください。

脚注を使用する必要がある場合は、Markdown にネイティブな脚注 ([^1]) を使用しなければなりません。 脚注マーカーは脚注リファレンスにハイパーリンクされ、ページの下部にマーカーへのバックリンクとともに表示されます。

使用する識別子 (文字、単語) に関係なく、脚注は連続した番号としてレンダリングされることに注意してください。

MonaUrsulaPaulDavy Jones1
お気に入りの娯楽出荷コード人魚をだます2スポーツの予測呪われた船員たち
力を適切に使用するはいいいえ有効いいえ
| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

ヘッダー

ヘッダーは、その下にあるコンテンツを適切に説明するものである必要があります。 ヘッダーは、タイトルを記述するためのガイドラインに従うか、質問として記述できます。 すべてのヘッダーの先頭文字に大文字を使用します。

記事にヘッダーがある場合、そのヘッダーは H2 レベルのヘッダーで始まる必要があります。 H3 レベルと H4 レベルのヘッダーを使用すると、さらにコンテンツを関連するグループに整理できますが、ヘッダー レベルをスキップすることはできません。 タイトルとサブタイトルの間には、紹介などのテキストが必ず入っています。

  • 以下を使用してください。

    ## HEADER (H2)

TEXT

### SUBHEADER (H3)

TEXT

#### SUBHEADER (H4)

TEXT

  • 以下は使いません:

    ## HEADER (H2)

#### SUBHEADER (H4)

ページ上の同一レベルの各ヘッダーは一意である必要があります。

  • 以下を使用してください。

    ## Examples  (H2)

TEXT

### Prompts for writing code (H3)

TEXT

### Prompts for writing tests (H3)

TEXT

  • 以下を使用してください。

    ## Prompts for writing code (H2)

TEXT

### Example (H3)

TEXT

## Prompts for writing tests (H2)

TEXT

### Example (H3)

TEXT

  • 以下は使いません:

    ## Example prompts (H2)

TEXT

### Example (H3)

TEXT

### Example (H3)

TEXT

画像

GitHub では、テキスト情報を補完するために、ドキュメント全体でスクリーンショット、図、グラフなどの静的イメージを使っています。

ドキュメントではアニメーション GIF を使わないでください。

代替テキスト

すべてのイメージに、ビジュアル情報に対応するテキストを伝える代替テキストを含める必要があります。

  • イメージを文字どおり説明するのではなく、中心となるアイデアや意味を表現します。
  • 40 から 150 文字にします。
  • 最後に句読点を付けます。 代替テキストが説明しているイメージのテキストが、疑問符や感嘆符など、他の句読点で終わっていない限り、通常これはピリオドです。
  • "イメージ..." や "グラフィック..." で始めないでください。 これは、スクリーン リーダーが自動的に伝えます。
  • "... のスクリーンショット" や "... を示す図" のように、グラフィックの "種類" から始めてください。
  • 記事のテキストで UI 要素の説明に使われている標準的な表現に従います。
  • メニュー項目の名前など、複数単語のタイトルは、二重引用符 ("") で囲みます。
  • イメージの領域が視覚的に強調表示されている場合は、どのように強調表示されているかを説明します。 これによって、スクリーン リーダーのユーザーは、探している対象について理解し、目の見える友人や同僚に視覚的言語の観点から説明することができます。

スクリーンショットの代替テキスト

代替テキストは、スクリーンショットを見ることができないユーザーにその内容を簡潔に伝える有用なものです。

  • 代替テキストには、細かい内容をすべて含めるのではなく、イメージの最も関連する要素を含める必要があります。
  • 代替テキストは、GitHub インターフェイスを使う手順を伝えるためのものではありません。 これは、記事に付けられているテキストに含まれているはずです。
フォーマット

Product name + UI element を示すスクリーンショット。 UI element + state of the element/controls とその keyboard shortcut XYZ が濃いオレンジ色の枠線で囲まれています。

  • Product name には、"GitHub" のみを使うのではなく、"GitHub Actions" や "GitHub リポジトリ" など、GitHub の製品名または機能名を使います。
  • コピーの実行するときのように、GitHub という単語には変数 {% data variables.product.prodname_dotcom %} を使います。
  • 記述されたドキュメントと矛盾しないように UI 要素を説明します。
  • わかりやすくするために、語順は必要に応じて柔軟に設定してください。
    • 例えば、一行に複数の名詞が含まれるのを避ける為、"スクリーンショットの Visual Studio Code デバッグ メニュー..." ではなく、"Visual Studio Code のデバッグ メニュー スクリーンショット..."と書いてください。
例

リポジトリ テーブル別の GitHub コミッターのスクリーンショット。 横方向のケバブ アイコンと [CSV レポートのダウンロード] ボタンが濃いオレンジ色の枠線で囲まれています。

GitHub リポジトリ内のファイル オプションのスクリーンショット。 [コード] というラベルが付いたボタンがドロップダウン メニューを示す矢印とともに濃いオレンジ色の枠線で囲まれています。

GitHub リポジトリ内のファイル オプションのスクリーンショット。 [コード] というラベルが付いたボタンがドロップダウン メニューを示す矢印とともに濃いオレンジ色の枠線で囲まれています。

図とグラフの代替テキスト

図またはグラフで伝えられている情報を、ページ上のテキストで説明します。

Web ページのテキストと重複させることなく、代替テキストを使ってイメージの中心となるアイデアを表現します。

例

GitHub Actions ランナーを名前付きクラスに自動的に追加して特定のジョブによって要求できるようにする 5 段階のプロセスを示す図。

例については、「アクション」ドキュメントでこの図に付けられている説明を参照してください。

コマンドライン インターフェイスのイメージの代替テキスト

コマンドライン インターフェイスのスクリーンショットは、コマンドとその出力を伝える目的には使わないでください。 代わりに、ユーザーが使う必要があるコマンドを直接示してください。 詳細については、スタイル ガイドの「コマンド」セクションを参照してください。

コマンド ライン インターフェイスのスクリーンショットを使ってユーザー インターフェイス要素を示す場合は、スクリーンショットの代替テキストに関する標準のガイドラインに従ってください。

イメージのファイル名

イメージ ファイルには、ファイル名に名前、アクション、UI 要素を含めて、わかりやすい名前を付けてください。 製品の言語を示します。 ケバブ ケースを使います。 ファイル名には Liquid 条件を使わないでください。 イメージを置き換える場合は、ファイル名をそのまま使います。

  • 以下を使います: data-pack-purchase-button.png
  • 以下は使いません: purchase_button.png
  • 以下は使いません: purchase-button-for-admins.png

Screenshots (スクリーンショット)

イメージの作成とバージョン管理の詳細については、スクリーンショットの作成と更新に関するページを参照してください。

図

ダイアグラムの作成の詳細については、「GitHub Docs のダイアグラムの作成」を参照してください。

インクルーシブな言語

世界最大の開発者コミュニティのホームとして、GitHub では、事業のあらゆる側面で多様性とインクルージョンを促進する取り組みを行っています。 GitHub のすべてのドキュメントは、世界中のさまざまな状況にある人々で構成されている対象ユーザーをインクルーシブに尊重しています。 ドキュメントを作成するときは、インクルーシブかつ反人種差別的で、わかりやすい単語を使っています。

1 つ 1 つの単語は小さなものですが、これらを集めれば、コミュニティ、一体感、公平性が生み出されます。 親身になって単語やスタイルを選んでください。 ユーザーやコミュニティについて言及する場合は、的確であってください。

用途回避
許可リストホワイトリスト
拒否リストブラックリスト
default/main ブランチmaster ブランチ

インクルーシブな言語に関するリソース

Microsoft スタイル ガイドには、バイアスフリーなコミュニケーションに関するリソース、アクセシビリティ用語、あらゆる能力についての記述が用意されています。

インクルーシブでわかりやすい言語とスタイルについて学ぶためのリソースは他にもあります。

キーボード ショートカット

キーボード ショートカットを表示する場合は、Microsoft スタイル ガイドに従ってください。ただし、次のような相違点は例外です。

  • 個々のキーごとに、HTML <kbd> タグを使います。

    • 以下を使います: <kbd>Command</kbd>+<kbd>B</kbd>
    • 以下は使いません: Command+B

  • Apple 修飾子キーには、記号の代わりに完全な単語を使います。

    • 以下を使います: Command
    • 以下は使いません: ⌘

  • 特殊文字のキーには、完全な単語ではなく、記号を使います。

    • 以下を使います: .、,、→。
    • 以下は使いません: Period、Comma、Right arrow。

使い方のポイント

GitHub のドキュメントでのキーボード ショートカットの表現方法について、次のように、使い方のポイントをいくつか紹介します。

  • 基本構文では、組み合わせたキーの間に + を入れて表示します。スペースは使いません。

    • 以下を使います: <kbd>Command</kbd>+<kbd>B</kbd>。Command+B のように表示されます。
    • 以下は使いません: <kbd>Command</kbd> + <kbd>B</kbd> または <kbd>Command + B</kbd>。Command + B または Command + B のように表示されます。

  • 一般的なリファレンスとキーボード ショートカットでは、文字キーは常に大文字で表します。

    • 以下を使います: Command+B
    • 以下は使いません: Command+b。

  • 各オペレーティング システムでの正しい修飾子キーを使います。

    注意: Windows と Linux では省略形の Ctrl ですが、Mac では完全なスペルの Control が使われています。

    • Windows と Linux の場合:

      • 以下を使います: Ctrl、Alt.
      • 以下は使いません: Control

    • Mac の場合:

      • 以下を使います: Command、Option、Control。
      • 以下は使いません: Cmd、⌘、Opt、⌥、Ctrl、⌃

  • キーを組み合わせて使う場合とキーを続けて押す場合とを混同しないようにしてください。

    • Command+B は、ユーザーが Command を押しながら B キーを押す必要があることを示しています。
    • G I は、ユーザーが G を押してから I キーを押す必要があることを示しています。

  • 複数のオペレーティング システムのキーボード ショートカットについて説明する場合は、ショートカットの後にオペレーティング システム名をかっこ内に追加します。 最初に Mac のショートカットについて説明し、次に Windows および Linux について説明します。

    • 以下を使います: <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux)。次のように示します。

      Command+B (Mac) または Ctrl+B (Windows および Linux)

    • 以下は使いません: <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>。次のように示します。

      Ctrl+B または Command+B

ライセンス付きのコンテンツ

GitHub Docs は、CC-BY ライセンスでライセンスされています。 記事内のライセンス付きコンテンツを再利用または変更する場合は、そのライセンスに互換性があり、属性が適切であることを確認する必要があります。

ライセンス属性に対して Reusables を作成しないでください。 属性が正確に記述されて記事内に表示されるように、プロジェクトに付与されているライセンスが従っているライセンスを使う必要があります。

コンテンツの再利用の適法性が不確かな場合は、法務部門に問い合せてください。 次に記載されていないライセンスが付いたコンテンツを追加する場合は、そのコンテンツを公開する前に法的審査を受ける必要があります。

MIT ライセンス付きコンテンツの属性付け

MIT ライセンスを受けたコンテンツを再利用または変更する場合は、そのコンテンツが表示される場所に MIT ライセンスを属性付けする必要があります。

MIT ライセンス付きコンテンツを含む記事の最後で、次を行います

  • Legal notice というタイトルのヘッダーを作成します
  • コンテンツの取得元を、MIT ライセンスでライセンスされているものとして属性付けします。 プロジェクトへのリンクを含めます
  • コードブロックに属性付けしているプロジェクトの MIT ライセンスの全テキストを貼り付けます

MIT ライセンス属性の例

このテキストは、あくまで例です。 必ず属性付けしているプロジェクトのライセンス テキストを使ってください。

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

改行

プレーン テキストの場合、ソース内で段落を区切るには、ソース内に視覚的なスペースを入れるのではなく、改行を使います (2 回連続で改行)。 特にリストでは、不要な改行は避けてください。

リンクは、ユーザーを追加情報に接続したり、複数の記事を読む必要があるタスクを進めるために使用されます。

リンクを使用して倹約する。 リンクが多すぎると、メイン コンテンツから気が散ったり、ユーザーの関心が奪われたりする可能性があります。 すべてのリンクは、ユーザー体験のコンテキストで考慮する必要があります。このリンクに誰かを送信する理由と、タスクを完了するためにその人たちを軌道に戻す方法とは?

リンクを追加する前に、他のユーザーがリンクにアクセスしてコンテンツを理解する必要があるかどうか、または GitHub を使用して成功する必要があるかどうかを判断します。

  • リンクが不要な場合は、削除します。
  • リンクが記事のメイン トピックに関連し、他のユーザーが学習を続けることができるが、タスクを完了する必要がない場合は、記事の最後に参考資料としてリンクを移動することを検討してください。
  • リンクによって誰かがプロセスの次のステップに進む場合は、記事の最後にある次の手順セクションにリンクを含めます。
  • タスクの完了や手順のトラブルシューティングに不可欠な情報がリンクに記載されている場合は、記事の本文にリンクを含めます。

リンクは一貫性があり、できるだけ多くのユーザーがアクセスでき、翻訳可能で、明確である必要があります。 ユーザーは、リンクがどこにつながり、達成したいこととどのように関係しているかを知る必要があります。

リンクを使う場合のいくつかのベスト プラクティスを紹介します。

  • リンクは、意味を持っており、ユーザー体験に高い価値をもたらします。 慎重にリンクします。
  • 同じ記事内、同じリンクを 2 回以上繰り返して表示しないでください。
  • 同じ記事のセクションへのリンクの後に、「この記事の前半/後半」を追加することを検討してください。
  • REST リンクには apiVersion クエリ パラメーターを含めないでください。ただし、REST ドキュメントの特定のカレンダー バージョンにリンクする必要がある場合を除きます (このようなことは、めったにありません)。

コンテキストからリンクの目的が明確であれば、単に "表示する" などの動詞でリンクを導入できます。 コンテキストが明確でない場合は、フレーズまたは文を使って、"詳細については、～を参照してください" あるいは "X についてさらに学習するには、Y を参照してください" などのリンクで紹介します。

リンク テキストとして、ドキュメント記事 (外部 Web ページ) のタイトルを使用します。 GitHub Docs サイトの別の記事を指すリンクの場合は、リンク テキストに特別なキーワード (AUTOTITLE) を使います。 詳しくは、コンテンツ マークアップ リファレンスをご覧ください。

リンクにスタイルを適用したり、引用符で囲んだりしないでください。

  • 他のページへのリンクの場合: See [AUTOTITLE](/PATH/TO/PAGE).
  • 他のページのセクションへのリンクの場合: For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

インライン リンクは使用しないでください。インライン リンクの場合、文中の単語にはリンクが含まれていることを示す単語を追加することなくハイパーリンクが設定されます。 翻訳し読むのが難しい場合があります。

ハイパーリンクには句読点を含めないでください。

  • 以下を使います: OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
  • 以下は使いません: Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

場合によっては、あるバージョンの GitHub Docs から別のバージョンにリンクする必要があります。 別のバージョンの "同じ" ページにリンクする場合は、currentArticle プロパティを使う必要があります。__

たとえば、Free、Pro、Team バージョンの「組織の GitHub Pages サイトの公開を管理する」は、次のように GitHub Enterprise Cloud バージョンの同じ記事にリンクされている場合があります。

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

別のバージョンの別の記事にリンクするには、次の形式を使います。

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

別のバージョンの同じ記事にリンクするには、次の形式を使います。

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

特定のバージョンにリンクするには、パスにバージョンを含める必要があります (例: /enterprise-cloud@latest/{{ currentArticle }})。

記事の特定のセクションへのリンクは、リンクをフォローした後に正しい場所にあることを理解できるほど説明的である必要があります。

同じ記事の特定のヘッダーにリンクするには、次の形式を使います。

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

同じページのセクションへのリンクは、AUTOTITLE を使うと機能しません。 代わりに、完全なヘッダー テキストを入力します。

別の記事の特定のヘッダーにリンクするには、次の形式を使います。

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

別の記事の特定の複数のヘッダーにリンクするには、次の形式を使います。

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

特定のツールが選択されたコンテンツにリンクする場合は、他のユーザーが記事のツール スイッチャー タブを操作していない場合でも、リンクが特定のツール用であることを確認してください。

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

ラーニング パスにリンクするには、次の形式を使います。

For more information, follow the [LEARNING PATH TITLE](/) learning path.

外部サイトにリンクする場合は、リンクのコンテキストに最も役立つリソースを選択します。 サイト全体が一般的な参照である場合は、サイト全体にリンクすることも、より役に立つ場合は特定のページにリンクすることもできます。

外部製品について言及されている場合に、外部製品の Web サイトにリンクする必要はありません。

外部ページ (GitHub によって管理されていない Web サイト) へのリンクについては、ページ全体のタイトルとリンク先サイトを入力します。 リンクを引用符で囲まないでください。

  • 以下を使います: See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.
  • 以下は使いません: See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).
  • 以下は使いません: See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).

記事の特定のセクションへのリンクがあることがわかっている場合は、セクションにアンカーを追加してそのリンクを保持できます。 たとえば、外部リソースが記事の特定のセクションにリンクしている場合は、セクションタイトルが変更された場合でもリンクが正しいセクションに移動させるようにアンカーを追加できます。

リンク アンカーには、この形式を使用します。 アンカー名は、保持されているセクション名にする必要があります。 アンカーを追加する理由を説明するには、HTML コメントを使用します。

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

リスト

リストの各行の最初の文字は大文字にします。 リスト内の行に完全な文章が含まれている場合のみ、行の最後にピリオドを使います。

主テキストと 2 番目のテキスト (たとえば、term とその定義) から構成されるアイテムのリストを作成する場合は、コロン区切り記号を使います。 2 番目のテキストは、行頭のように大文字にする必要があります。 たとえば次のような点です。

  • foo: bar を指定するもの。
  • bar: foo によって指定されるもの。

順不同のリストの書式設定:

  • リスト内でアイテムの順序が重要ではない場合は、リスト アイテムをアルファベット順にします。
  • 順序が重要な場合は、読者にとって重要な順序でリストを並べ替えます (たとえば、該当する対象ユーザーが最も多いものから、対象ユーザーがより特化されるものに向けて移動させます)。
  • リスト アイテムにはアスタリスク (*) を使用します。

リストを導入する場合は、ローカライズしにくい "以下の" や "これらの" などの用語を使用した、短くて抽象的な言い回しは避けてください。 代わりに、リストの主題を明確に伝え、その上説明を更新せずにリストを拡大縮小したり変更したりできる説明文を作成します。

以下を使用してください。

  • GitHub の概要については、次の記事を参照してください。
  • SMS 認証は以下の国でサポートされています。

以下は使いません:

  • GitHub について紹介した記事がいくつかあります。 以下を参照してください:
  • SMS 認証は 50 か国でサポートされています。 これには以下が含まれます。

許可ステートメントと製品コールアウト

権限ステートメントと製品コールアウトを使用して、特定の役割または製品を完了する必要があるタスクを伝達します。

  • アクセス許可ステートメント: この記事で説明されているアクションやタスクを実行するために必要な役割。 例: "エンタープライズ オーナー"
  • 商品コールアウト: 記事で説明されているアクションを実行したりタスクを実行したりするために必要な PRODUCT。 例: "Copilot Business のサブスクリプションを含む、Organization アカウントと Enterprise アカウント"

許可ステートメントと PRODUCT コールアウトは、記事で説明されている機能を誰が使用できるかを読者に伝えます。

スキャン可能な商品コールアウトの作成に関するガイドライン

アクセス許可と成果物要件を定義する

アクセス許可ステートメントまたは PRODUCT コールアウトにどのような情報が含まれるかを検討します。

たとえば、記事「organization 内での Copilot のポリシーの管理」のアクセス許可と製品吹き出しを作成する場合、アクセス許可ステートメントは "Organization 内の GitHub Copilot のポリシーと機能を管理できるロールは何か" という回答になります。 また、PRODUCT コールアウトは、"組織の Copilot のポリシーと機能を管理するには、ユーザーがどの Copilot サブスクリプションを必要とするか?" という回答になります。

各説明ではなく、重要な情報に焦点を当てる

アクセス許可ステートメントと PRODUCT コールアウトは、タスクを実行できるユーザーと必要な PRODUCT を伝える必要があります。 役割や PRODUCT が必要な理由を説明する必要はありません。

アクセス許可ステートメントまたは PRODUCT コールアウトに複数のロールまたは PRODUCT が適用される場合は、順序なしリストを使用して書式設定します。 文章で、複雑なアクセス許可ステートメントや PRODUCT コールアウトを紹介できますが、記事の内容を誰が実行できるかを伝えるために、常に必要な単語を少なくするようにしてください。

インライン リンクを使用して、役割または PRODUCT に関する詳細情報を提供できます。 リンク先のテキストは、リンクをたどるとどこにつながるかが明確になるように、リンク先と一致する必要があります。

プレースホルダー

プレースホルダー テキストをすべて大文字でスタイル設定します。 プレースホルダーが複数のワードの場合は、単語をダッシュ (kebab-case) で接続します。 プレースホルダーを使用する場合は、名前未登録ユーザーが置き換える可能性のあるものを説明します。 これは、参加者がニーズに合わせて例をサイズに合わせて調整するのに役立ち、支援技術を使用する参加者のプレースホルダーを識別するのに役立ちます。

以下を使用してください。

  • 次の例では、YOUR-REPOSITORY をリポジトリの名前に置き換えます。 git init YOUR-REPOSITORY
  • [新しいユーザー名の追加] をクリックします。 USERNAME は、追加する個人のユーザー名です。

以下は使いません:

  • git init your repository
  • git init <your-repository>
  • [新しい_ユーザー名の追加]_ をクリックします。

手順に沿ったステップ

手順を使うと、読者は、タスクを完了するために従う一連のステップを把握できます。 手順には、番号を付けたリストを必ず使います。 タスクを完了するために必要なすべての前提条件や概念に関する情報は、特定のステップに含めるのではなく、手順の前に読者に伝えます。

各ステップにはアクションを含める必要があります。 また、アクションの完了に向けたガイダンスの前に、ステップが省略可能かどうかについて伝えたり、ステップの理由または結果について説明したり、読者にアクションの場所を説明して案内したりすることもできます。

各ステップ内の情報は、一貫した順序で示してください。

  1. ステップが省略可能な場合は、それを最初に示します。
  2. わかりやすくするために必要な場合や、破壊的または複雑なアクションの重要度を上げるために必要な場合は、ステップの理由または結果について説明します。
  3. ユーザーがアクションを確認する場所について説明します。
  4. Action(アクション)。

以下を使います: 必要に応じて、REASON を示し、LOCATION で、ACTION を実行します。

例:

  • [支払い情報] をクリックします。
  • Organization の名前の下にある [設定] をクリックします。
  • 変更を確定するには、 [クレジット カードの削除] をクリックします。
  • プランの詳細を確認するには、必要に応じて、 [詳細の表示] をクリックします。
  • [GitHub Sponsors] の、スポンサード オープン ソース コントリビューターの右で、自分がスポンサーした額の隣にある をクリックし、[層の変更] をクリックします。

製品名

完全な製品名を使います。 製品のコンテンツ (UI のコピーや API 応答など) を直接再現する場合を除き、製品名は省略または短縮しないでください。 製品名は所有格にしてはなりません。

製品名を表示するには、製品名変数を使います。プレーン テキストに製品名を書き込まないでください。 これにより、サイト全体で製品名を簡単に変更できるとともに、製品名の入力ミスを回避できます。 製品名変数について詳しくは、このドキュメントの「再利用可能と変数」、または github/docs リポジトリのデータ ディレクトリをご覧ください。

製品名は常に単数形です。

  • 以下を使います: GitHub Actions は、ソフトウェア開発ワークフローの自動化に役立ちます (訳注: 原文では「helps」)。
  • 以下は使いません: GitHub Actions は、ソフトウェア開発ワークフローの自動化に役立ちます (訳注: 原文では「help」)。

製品名と製品機能は、注意して区別してください。 製品機能は常に小文字です。

Product機能
GitHub Actionsアクション
GitHub Codespacescodespace
GitHub Packagesパッケージ
GitHub PagesGitHub Pages サイト

pull request、topic、issue など、一般的に使用される機能を大文字にしないでください。

製品固有の規則

このセクションでは、GitHub 製品に固有のその他の規則について説明します。

GitHub Actions

ファースト パーティ アクションの Reusables

ファースト パーティ アクションを使うコード例では、そのアクションに Reusables を使う必要があります。 これにより、将来の GitHub Enterprise Server リリースまで同じアクション バージョンを利用できない可能性がある GitHub Enterprise Server のような製品のアクション バージョンの更新 (v1 から v2 など) を簡単に管理できるようになります。

アクション Reusables は、/data/reusables/actions/ にあり、action-<action_name>.md のようなファイル名が付けられています

たとえば、例で actions/checkout アクションを使うには、その Reusables を使います。

steps:
  - name: Checkout
    uses: actions/checkout@v4

GitHub Docs の目的上、ファースト パーティ アクションは、actions/ プレフィックス、github/ プレフィックス、または octo-org/ プレフィックスを持つアクションです。 たとえば、これはファースト パーティ アクションです。

steps:
  - uses: actions/checkout@v4

サード パーティ アクションに関する免責事項

サード パーティ アクションを使うコード例には、コード ブロックの一部として次の免責事項を含める必要があります。

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

この免責事項を挿入するには、{% data reusables.actions.actions-not-certified-by-github-comment %} Reusables を使います。

GitHub Docs の目的上、サード パーティ アクションは、actions/ プレフィックス、github/ プレフィックス、または octo-org/ プレフィックスを持たないアクションです。 たとえば、これはファースト パーティ アクションです。

steps:
  - uses: actions/checkout@main

これは、サード パーティ アクションの例です。

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

例 :

SHA へのバージョン番号のピン留め

サード パーティのアクションを使うコード例では、バージョン番号やブランチではなく、必ず完全な長さのコミット SHA にピン留めする必要があります。

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

GitHub Docs の目的上、サード パーティ アクションは、actions/ プレフィックス、github/ プレフィックス、octo-org/ プレフィックスのいずれかを持たないアクションです。 たとえば、これはファースト パーティ アクションです。

steps:
  - uses: actions/javascript-action@main

詳細については、「SHA の使用」を参照してください

Codespaces

製品 Codespaces について言及する場合は、次の状況を除き、必ず "GitHub" を含めてください。

  • shortTitle front matter で。
  • 記事内の小見出し。記事内のどこかで、小見出しの前に、"Codespaces" が既に使われていた場合。

変数: {% data variables.product.prodname_github_codespaces %} ("GitHub Codespaces") と {% data variables.product.prodname_codespaces %} ("Codespaces")。

このテクノロジを使ってリモート作業環境のインスタンスを参照する場合は、これを "codespaces" (c は小文字) として参照してください。 たとえば、"codespace を削除するには" や "codespaces を一覧表示するには" のようにします。

ファイル名やパス名を除き、"開発コンテナー" には、必ず "dev container" (または、明確に示す必要がある場合は、長い形式の "development container") を使います。"devcontainer" (1 語) は使いません。 1 つの単語は、ブランドと見なされてしまうことがあるため、避ける必要があります。また、 Visual Studio Code documentationで使われている 2 つの単語の形式に合わせる必要もあります。

.devcontainer ディレクトリ内のすべてのファイル (また、.devcontainer ディレクトリ内の devcontainer.json 以外で使われている場合は、.devcontainer.json) を参照するには、"development container configuration files" (開発コンテナー構成ファイル) を使います。 devcontainer.json ファイルを参照していると見なされないように、これらを "development container files" や "devcontainer files" (開発コンテナー ファイル) として参照しないでください。 "development container configuration files" (開発コンテナー構成ファイル) は、開発コンテナーを構成するために使うことができるすべてのファイル (Dockerfile ファイルと docker-compose.yml ファイルを含みます) を指します。 明確に devcontainer.json ファイルを参照する場合は、"the development container configuration file" (単数形の "開発コンテナー構成ファイル") を使わないでください。 代わりに、このファイルは、その名前で参照してください。

GitHub Advanced Security (GHAS)

GitHub Advanced Security の支払いについて言及する場合は、licenses や active committers という用語を使います。

以前は、Enterprise 内で GitHub Advanced Security を使うことができるアカウントの数は、seats という用語を使って示していました。 seats という用語はユーザーの混乱を招く場合があるため、2022 年秋にこの用語を GitHub.com から削除し、GHES 3.7 以降のバージョンではこれを使っていません。

Personal access tokens

GitHub には、2 種類の personal access tokens があります。

  • Fine-grained personal access token: リポジトリのアクセスとアクセス許可をきめ細かく制御できます
  • Personal access token (classic): スコープを使い、トークン所有者がアクセスできるすべてのリポジトリへのアクセス権を付与します

一般的に personal access tokens に加え、これらの種類のトークンを参照するには、変数を使う必要があります。

  • 一般的に personal access token を参照するには、{% data variables.product.pat_generic %} または {% data variables.product.pat_generic_caps %} を使います。 UI テキストに一致させるために、語句をタイトル ケース ("Personal Access Token") にする必要がある場合は、{% data variables.product.pat_generic_title_case %} を使います。
  • fine-grained personal access token を参照するには、{% data variables.product.pat_v2 %} または {% data variables.product.pat_v2_caps %} を使います。
  • personal access token (classic) を参照するには、{% data variables.product.pat_v1 %}、{% data variables.product.pat_v1_plural %}、{% data variables.product.pat_v1_caps %}、または {% data variables.product.pat_v1_caps_plural %} を使います。

GitHub の personal access tokens の詳細については、「個人用アクセス トークンを管理する」を参照してください。

句読点

標準の米国英語の句読点のルールに従います。 詳しくは、Microsoft スタイル ガイドの「句読点」をご覧ください。

リリース ノート

GitHub Docs の一連のリリース ノートは、GitHub Enterprise Server (GHES) などの製品のバージョン管理されたリリースに対する、管理者またはユーザーを対象とした変更を読者に伝えるものです。 リリース ノートは、「リリース ノート」に記載されます。

優れたリリース ノートには、少ない数の文章の後に、変更についての読者からの質問への答えが記載されています。 詳しくは、「リリース ノートコンテンツタイプ」をご覧ください。

一連のリリース ノートではそれぞれ、次の変更のいずれかについて説明しています。

  • 機能: 新しい動作や機能
  • セキュリティに関する修正: セキュリティに影響を及ぼす欠陥または予期しない動作に対する修正
  • バグの修正: 欠陥または予期しない動作に対する修正
  • 変更点: 過去の動作に対する注目すべき変更
  • 既知の Issue: GitHub が特定したが、まだ優先順位を付けられない、または付いていない Issue
  • 非推奨: 機能または動作 の終了
  • 正誤表: 不正確なリリース ノートまたはドキュメントに対する訂正

また、「リリース ノートの追加または更新」と「リリース ノートの削除」でリリース ノートの更新に関するガイドラインを確認することもできます。

機能

機能についてのリリース ノートでは、新しい動作の概要を伝えます。 一般的に、機能についてのノートは、機能リリースのほんの一部です。

機能についてのリリース ノートの作成

機能についてのリリース ノートでは、次のような質問に答えます。

  1. この新しい機能は、自分のロールやアクセス権を含め、自分に当てはまりますか?
  2. この機能を使うと、どのようなニーズが満たされますか?
  3. これはどのような機能ですか?
  4. 該当する場合、この機能について、どこで詳しく確認できますか?

"対象ユーザー" (1) は、"機能の使い方の説明" (3) によって、"ニーズの説明" (2) できます。__ __ __ 詳しくは、「"記事のタイトル"」 (4) をご覧ください。__

  • 機能を見出しにして、その下に各機能をセクションに分けます。
  • 現在形で書きます。
  • 単語の繰り返しや不要な単語を減らすために、通常は "現在" が暗黙的に使われます。
  • アクターと影響を明確にするには、できるだけ受動態を使わないでください。

機能リリース ノートの例

  • 管理コンソールのセキュリティを強化するために、サイト管理者は、サインイン試行のレート制限と、レート制限を超えた後のロックアウト期間を構成できます。 詳細については、「レート制限の構成」を参照してください。

  • Enterprise 所有者は、ユーザーがリポジトリをフォークできる場所を制御できます。 フォークを、Organization の事前設定された組み合わせ、親リポジトリと同じ Organization、ユーザー アカウント、またはすべての場所に制限できます。 詳細については、「Enterprise でリポジトリ管理ポリシーを適用する」を参照してください。

  • ユーザーは、geoJSON、topoJSON、STL のダイアグラムを使ってファイルを作成し、Web インターフェイスでダイアグラムをレンダリングできます。 詳細については、「非コード ファイルでの作業」を参照してください。

セキュリティに関する修正

セキュリティに関する修正についてのリリース ノートでは、製品のセキュリティ関連の問題を軽減したり悪用を防いだりする変更の概要を伝えます。 一般的に、セキュリティに関する修正のついてのノートは、パッチ リリースのほんの一部です。

セキュリティに関する修正についてのリリース ノートの作成

セキュリティに関する修正についてのリリース ノートでは、次のような質問に答えます。

  1. 利用可能な場合、修正済みの脆弱性に対する NVD 脆弱性の重大度の評価とは、どのようなものですか?
  2. 攻撃者が脆弱性を悪用して実行する攻撃とは何ですか?
  3. 悪用できる脆弱性には、どのような種類がありますか?
  4. 利用可能な場合、保留中またはアクティブな脆弱性の CVE 識別子とは何ですか?
  5. GitHub バグ報奨金プログラムで脆弱性を報告した人はいましたか?

"重大度" (1): 攻撃者が、"悪用の説明" (3) によって、"影響の説明" (2) 可能性があります。__ __ __ GitHub は、この脆弱性の CVE ID CVE-####-##### (4) を要求しました。これは、GitHub バグ報奨金プログラム (5) で報告されています。

セキュリティに関する修正についてのリリース ノートの例

  • 中: 攻撃者が、Markdown REST API に対する並列要求を行うことによって、インスタンス上での無制限のリソース枯渇を引き起こした可能性があります。 この問題を解決するために、GitHub は、CommonMarker を更新しました。 GitHub は、この脆弱性の CVE ID CVE-2022-39209 を要求しました。

  • 中: URL が pull request プレビュー リンクによって適切にサニタイズされなかったため、攻撃者が、インスタンスの Web UI に危険なリンクを埋め込んだ可能性があります。 この脆弱性は、GitHub バグ報償金プログラムで報告されています。

BASE Imageとパッケージの更新

また、BASE Imageと依存パッケージの更新プログラムも「セキュリティ修正プログラム」セクションに含まれています。これらの更新プログラムはセキュリティの問題点に対処することが多いためです。 これらの更新プログラムはすべて、次のノートに合併されています。

パッケージは最新のセキュリティ バージョンに更新されました。

バグ修正

バグの修正についてのリリース ノートでは、望ましくない動作やその他の予期しない動作に対する修正について説明します。 一般的に、バグ修正のついてのノートは、パッチ リリースのほんの一部です。

バグの修正についてのリリース ノートの作成

バグの修正についてのリリース ノートでは、次のような質問に答えます。

  1. この動作は、自分のロールやアクセス権を含め、自分に影響していましたか?
  2. 修正前に読者が体験していたのは、どのような動作ですか?

"対象ユーザー" (1) "動作の説明" (2)。__ __

  • 現在、バグは修正されているので、過去形で書きます。
  • "バグを修正しました..." や "問題を修正しました..." のような表現は、黙示的であり、不要です。
  • 単語の繰り返しや不要な単語を減らすために、通常は "現在" が暗黙的に使われます。
  • アクターと影響を明確にするには、できるだけ受動態を使わないでください。
  • リリース ノートにエラー メッセージが含まれている場合は、「エラー メッセージ」のガイダンスに従ってメッセージの形式を整えます。

バグの修正についてのリリース ノートの例

  • プッシュ保護が有効になっているリポジトリをユーザーがインポートした後、そのリポジトリはセキュリティの概要の [セキュリティ カバレッジ] ビューにすぐには表示されませんでした。

  • GitHub Actions が有効になっているインスタンスでは、GitHub Actions のワークフロー ジョブは、このジョブがキューに入った後に一致するランナー グループが利用可能になっても、このジョブが最初にキューに入ったときに一致するランナー グループが利用できなかった場合は開始しません。

  • サイト管理者が任意のインスタンス ノードで SSH 経由で実行したコマンドは、/var/log/ssh-console-audit.log に記録されませんでした。

[変更点]

変更点についてのリリース ノートでは、既存の動作に対する注目すべきではあっても軽微な変更点について説明します。 変更点についてのノートでは、次のような質問に答えます。

変更点についてのリリース ノートの作成

変更点についてのリリース ノートでは、次のような質問に答えます。

  1. この動作は、自分のロールやアクセス権を含め、自分に影響していましたか?
  2. この変更によって解決または回避された問題とは、どのような問題ですか?
  3. 新しい動作とは、どのような動作ですか?
  4. 関連する場合、変更前はどのような動作でしたか?

"対象ユーザー" (1) / "変更点によって解決した問題の説明" (2) "新しい動作の説明" (3) "以前の動作の説明" (4)。__ __ __ __

  • 変更点は該当するリリースに適用されているため、変更点についてのノートは現在形で書いてください。
  • 単語の繰り返しや不要な単語を減らすために、通常は "現在" が暗黙的に使われます。
  • アクターと影響を明確にするには、できるだけ受動態を使わないでください。
  • 多くの場合、対象ユーザーは暗黙的です。
  • 役に立つならば、GitHub Docs への関連するリンクを含めてください。

変更点についてのリリース ノートの例

  • GitHub Advanced Security ライセンスを持つインスタンスでは、シークレット スキャンのカスタム パターンを作成するユーザーは、最大 2,000 文字の、一致しなければならない、または一致してはならない式を指定できます。 この制限は、1,000 文字から引き上げられました。

  • SAML マッピングをレビューまたは変更する必要がある管理者の場合、ghe-saml-mapping-csv -d からの出力の既定のパスは、/tmp ではなく、/data/user/tmp です。 詳細については、「コマンドライン ユーティリティ」を参照してください。

  • 複数のノードがあるインスタンスに対する Git 操作の成功に関する断続的な issue を回避するために、GitHub Enterprise Server により、SQL クエリを試行する前に MySQL コンテナーの状態が確認されます。 タイムアウト期間も短縮されました。

既知の問題

既知の問題についてのリリース ノートでは、GitHub によって特定されたが、優先順位を付けることができない、または優先順位がまだ付けられていない問題について説明します。

既知の問題についてのリリース ノートの作成

既知の問題についてのリリース ノートでは、次のような質問に答えます。

  1. この動作は、自分のロールやアクセス権を含め、自分に影響しますか?
  2. 表示されるエラー メッセージやその他の認識可能な UI 要素は何ですか?
  3. 対処する必要はありますか? その場合、どうすればよいですか?

"対象ユーザー" (1) "問題の説明" (2) "動作の詳細" (3) "次のステップ" (4)。__ __ __ __

  • アクターと影響を明確にするには、できるだけ受動態を使わないでください。
  • 単語の繰り返しや不要な単語を減らすために、通常は "現在" が暗黙的に使われます。
  • リリース ノートにエラー メッセージが含まれている場合は、「エラー メッセージ」のガイダンスに従ってメッセージの形式を整えます。
  • 役に立つならば、GitHub Docs への関連するリンクを含めてください。
  • 既知の issue も GitHub Docs のコンテンツの一種です。詳しくは、「トラブルシューティング コンテンツ タイプ」をご覧ください。 必要に応じて、ドキュメントにより詳細で文脈に沿ったコンテンツを書いてください

既知の問題についてのリリース ノートの例

  • 読み取りアクセス権を持つユーザーがディスカッションを作成できるように、あるユーザーがリポジトリのオプションを有効にすると、この機能は有効になりません。

  • 管理者が構成の実行を開始すると、Notebook サービスと Viewscreen サービスでの検証フェーズ中に No such object error が発生する可能性があります。 サービスが引き続き正しく起動するため、このエラーは無視することができます。

廃止予定

非推奨についてのリリース ノートでは、GitHub によって削除されたか削除が予定されている動作や機能の概要を伝えます。 一般的に、非推奨についてのノートは、機能リリースのほんの一部です。

非推奨についてのリリース ノートの作成

非推奨についてのリリース ノートでは、次のような質問に答えます。

  1. この既存の機能は、自分のロールやアクセス権を含め、自分に当てはまりますか?
  2. 非推奨になる機能は何ですか?
  3. 該当する場合、非推奨になった機能は何に置き換えられますか?
  4. 該当する場合、詳細はどこで確認できますか?

"対象ユーザー" (1) "非推奨の機能の説明" (2) "置き換わる機能" (3) 詳細については、「"記事のタイトル"」(4) を参照してください。________

  • ノートは現在形です。または、今後の変更の場合は未来形です。 該当する場合、非推奨が発生する今後のリリースを指定します。
  • 単語の繰り返しや不要な単語を減らすために、通常は "現在" が暗黙的に使われます。
  • アクターと影響を明確にするには、できるだけ受動態を使わないでください。
  • 機能を見出しにして、その下に各機能をセクションに分けます。

非推奨についてのリリース ノートの例

  • 今後の非推奨化: GitHub Enterprise Server 3.8 以降では、インスタンスのセキュリティを確保するため、管理シェルへの SSH 接続に対してセキュリティで保護されていないアルゴリズムが無効になります。

  • コミットのコメント (ユーザーが pull request の外部のコミットに直接追加するコメント) は、pull request タイムラインに表示されなくなります。 ユーザーはこれらのコメントに返信したり解決したりできませんでした。 タイムライン イベント REST API と GraphQL API の PullRequest オブジェクトもコミット コメントを返さなくなりました。

エラー

正誤表では、リリース ノートやリリースのドキュメントで以前公開されていた不正確な情報を修正します。

正誤表の作成

正誤表では、次のような質問に答えます。

  1. 該当する場合、リリース ノート、または GitHub Docs のコンテンツのどのセクションが影響を受けましたか?
  2. この正しくない情報は、自分のロールやアクセス権を含め、自分に該当しましたか?
  3. そのリリース ノートまたはドキュメントでは、何が不正確であると説明していましたか?
  4. この正誤表が公開されたのは、いつでしたか?

"コンテンツ" (1) に、"対象ユーザー" (2) が "不正確な情報の概要" (3) できると誤って記載されていました。__ __ __ [更新日: "公開日" 4]__

正誤表の例

  • 機能に関するページに、GitHub Advisory Database のユーザーが Elixir、Erlang の Hex パッケージ マネージャーなどのアドバイザリを表示できると誤って記載されていました。 この機能は GitHub Enterprise Server 3.7 では利用できず、今後のリリースで利用できるようになる予定です。 [更新日: 2023 年 6 月 1 日]

リリース ノートの追加または更新

注意を追加または変更したことを読者に通知したり、正誤表の公開日を示したりするには、"[更新日: YYYY-MM-DD]" という形式で datestamp を追加します。

リリースノートの削除

リリース ノートを削除したことを知らせるには、削除したノートと、(該当する場合は)削除されたノートが実際にどのバージョンに関係しているかを説明するための「正誤表」セクションを追加します。 「正誤表を書く」を参照してください。

Reusables と変数

個々の名詞 (製品名など) や完全な文章や段落に、再利用可能な文字列を使います。 文章の一部や語句は、コンテンツがローカライズされるときに問題を引き起こす可能性があるため、再利用可能な文字列には含めてはいけません。 詳細については、github/docs リポジトリのデータ ディレクトリ、「再利用可能なコンテンツの作成」、このドキュメントの「製品名」セクションを参照してください。

セクション目次

コンテンツをさらに分割するために記事のセクションで H3 ヘッダーや H4 ヘッダーを使っており、コンテンツの一部のみが読者に関連する場合は、最も関連する情報を読者が特定してそれに移動しやすくなるように、セクション目次を使うことができます。 たとえば、「Enterprise の監査ログのストリーミング」では、ユーザーはおそらく、「監査ログのストリーミングの設定」のセクション目次を使ってプロバイダーを選び、セクション全体を読まなくても関連するコンテンツに移動できるように、1 つのプロバイダーの監査ログ ストリーミングのみを設定します。

H3 ヘッダーや H4 ヘッダーをコンテンツのグループ化のみに使っており、すべての情報がユーザーに関連する可能性がある場合は、セクション目次を追加しないでください。 たとえば、「ID とアクセス管理について」では、ユーザーは、自分の Enterprise に関連するため、各セクションを読んで検討する必要があります。 この記事には、セクション目次を記載していません。ユーザーは、セクションを選り好みすることなく、各セクションを読了するはずだからです。 また、セクション目次を追加すると、スクリーンリーダーやその他のアダプティブ テクノロジを利用するユーザーが、さらに多くのヘッダーをタブ移動したりスクロールしたりしないと、探している情報が見つからないことにもなります。

セクション目次は、リストとして書式設定します。 すべてのサブセクションは、記事に表示される順序で記載し、完全なヘッダー タイトルを使って参照します。

セクション目次は、コンテンツがどのように編成されているかを理解して最も関連するセクションを選ぶのに役立つ文章や段落を使って導入する必要があります。 ヘッダーのすぐ下にセクション目次を記載しないでください。

セクション目次の例

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

Tables

テーブルは、Markdown を使用して GitHub Docs に追加されます。 テーブルの読み取りとメインが困難な場合があるため、テーブルを作成する前に、テーブル内のデータが、リストなどの別の形式ではなく、テーブルで最適に表されていることを確認してください。 テーブル内のすべての行は、| パイプ記号で始まり、パイプ記号で終わる必要があります。

表形式の情報を表示する場合にのみテーブルを使用する

テーブルは、比較が必要な情報や複数の属性を持つ値など、表形式のデータを示すのに最適です。 単純なリストにはテーブルを使用しないでください。このドキュメントの「リスト」セクションを参照してください。

テーブル データの説明は避ける

テーブルのデータとそれが重要である理由は、前のコンテンツ、列ヘッダー、および行ヘッダー (必要な場合) でわかるようにする必要があります。 テーブル内のデータを不必要に説明しないようにしてください。 長い説明を付けなければテーブル内のデータが明確ではない場合は、テーブルに行ヘッダーが必要かどうかや、情報を別の方法で伝えた方がよいかどうかについて検討してください。

たとえば、「セルフホステッド ランナーによる自動スケーリング」では、サポートされている 2 つの自動スケーリング ソリューションを比較するテーブルが、Each solution has certain specifics that may be important to consider. という文章と共に導入されています。この記事では、テーブルによって情報が明確に伝えられているため、比較対象のさまざまな機能については一切説明していません。

  • 以下を使います: "GHES のバージョンに応じて、リポジトリあたりの異なるサイズ制限が適用されます。"
  • 以下は使いません: "テーブルの 1 行目は、GitHub Enterprise Cloud に関する情報を示しています。 2 行目は、GitHub Enterprise Server に関する情報を示しています。"
  • 以下は使いません: "次のテーブルは、エクスポートされる移行データの種類を示しています。"

行ヘッダーと列ヘッダーに適切なマークアップを使う

1 行目でテーブル内のデータ値 (ただし、データそのものではありません) について説明しているテーブルは、行ヘッダーを使ってマークアップする必要があります。 これは、支援技術でセル間の関係を理解するために重要です。

たとえば、次のテーブルで、テーブル内の "はい" と "いいえ" の各値の意味を理解するには、列ヘッダー (ロール) と行ヘッダー (アクセス許可) の両方を把握する必要があります。

Organization の権限 所有者 メンバー モデレーター 支払いマネージャー セキュリティマネージャー
リポジトリを作成する はい イエス はい いいえ はい
支払い情報を表示および編集する はい いいえ 番号 有効 いいえ
Organization に参加するようユーザを招待する はい いいえ いいえ いいえ いいえ

Markdown テーブルに行ヘッダーを追加するには、Liquid タグ {% rowheaders %} {% endrowheaders %} にテーブルをラップします。 行ヘッダーの使用の詳細については、「GitHub Docs での Markdown と Liquid の使用」を参照してください。

すべてのセルの値を含める

テーブル内のすべてのセルには、何らかの値が必ず含まれています。

データのないセルでは、"なし" または "該当なし" を使用します。 "NA" や "N/A" は使わないでください。

行ヘッダーのあるテーブルでは、最初のセル (セル "A1") は、テーブル全体を理解するのに役立つ行ヘッダーを記述する必要があります。 ただし、これを行うとテーブルの明確性が低下したり冗長な情報が追加されたりする場合は、このセルを空のままにすることができます。 たとえば、記事「PowerShell のビルドとテスト」では、最初のセルに "モジュール" というラベルを付けることができましたが、各行ヘッダーには既に "モジュール" という単語があるので、このヘッダーはテーブル全体を理解するための説明的な値を追加しない情報を繰り返すことになります。

明確で一貫性のあるシンボルとラベルを使う

シンボルが使われているテーブルの場合は、次のようにします。

  • すべてのセルを設定します。 たとえば、アクセス許可テーブルでは、アクセス許可が必要なもののセルのみをマークしないでください。
  • octicon または SVG を使います。 絵文字は使わないでください。 Octicon の詳細については、「GitHub Docs での Markdown と Liquid の使用」を参照してください。
  • 肯定的な値 ("はい"、"必須"、"サポートされている") にはチェックマークを、否定的な値 ("いいえ"、"省略可能"、"サポートされていない") にはバツ印を使います。
  • 視覚的な特性ではなく、シンボルの意味を説明するには、aria-label を使います。 たとえば、"チェック マーク アイコン" ではなく、"必須" とします。

テーブル データが完全にバイナリ (たとえば、すべての値が "はい" か "いいえ" の場合) ではない場合は、シンボルに加えて、またはシンボルの代わりに、テキスト値が必要になる場合があります。 たとえば、「GitHub Supportについて」のページでは、一部の機能が "購入可能" とマークされています。

脚注は慎重に使う

「脚注」を参照してください。

テーブルの内容を一貫して配置する

テーブル内の列はすべて左揃えにする必要があります。例外として、octicon のみが含まれている列は中央揃えにします。 列にテキストと octicon の両方が含まれている場合は、中央揃えを使います。

既定では、テーブルの内容は左揃えです。 Markdown テーブルの書式設定では、コロン (:) をヘッダー列のダッシュの左側または右側に付けて、各列の配置を指定します。 詳細については、「情報を表に編成する」を参照してください。

次の例は、「Dependabot options reference」のテーブルの一部を示しています。

回答内容 必須 セキュリティ更新プログラム バージョン アップデート 説明
package-ecosystem 使用するパッケージマネージャー
directory パッケージマニフェストの場所
schedule.interval 更新を確認する頻度

テーブルは、次の配置構文で生成されます。

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

タイトル

タイトルの単語の先頭文字は大文字にします。

短いタイトル

GitHub では、サイドバーのナビゲーションを設定するために、短いタイトルを使っています。 短いタイトルはサイドバー移動に表示されるため、コンテキストを使用して意味を伝え、完全なタイトルよりも少し精度が落ちます。 短いタイトルのゴールは、サイドバー の移動品目が長すぎることなく、参加者が探している内容を見つけやすくすることです。 短いタイトルを使用すると、参加者は記事をコンテキストに応じて解釈し、次のStandardに位置を合わせます。

  • 短いタイトルの長さは 2 ～ 3 ワードです。
    • カテゴリの場合、短いタイトルは 27 文字未満にする必要があります。
    • 地図で表示する トピックの場合、短いタイトルは 30 文字未満にする必要があります。
    • 記事の場合、短いタイトルは 31 文字未満にする必要があり、20～ 25 文字が理想的です。
  • 短いタイトルでは、動名詞の代わりに動詞の原形が使用されます。
    • 使用する:「Configuring notifications.」(通知を構成すること) ではなく「Configure notifications」(通知の構成)を使用します。
  • カテゴリ、地図で表示するトピック、および記事の短いタイトルでは、関連する PRODUCT または機能が明確であれば、製品名と機能名を省略できます。
    • 使用する: 「Dependabot アラートの通知を構成する」を短縮したタイトルとして「通知を構成する」を使います。これは、記事が「Dependabot alerts」マップ トピックに含まれているためです。
  • 完全なタイトルに含まれていない新しいワードは、短いタイトルには入れないでください。
  • 短いタイトルは、同様の内容の短いタイトルに対応している必要があります
    • 使用する:「Organization とチーム」と「Enterprise アカウント」
    • 回避する:「Organization とチーム」と「Enterprise アカウントの管理」

短いタイトルを書き込むのはチャレンジングな場合があります。 短いタイトルを文字数未満に収まるようにするには、コンテキストで短いタイトルを検討してください。 可能であれば、繰り返されるワードと、コンテンツが属する地図で表示するトピックまたはカテゴリ内の PRODUCT 名または機能名を削除します。

サイト ポリシーのコンテンツ

サイト ポリシー コンテンツで再利用可能な変数や変数を使用しないでください。 サイト ポリシーの記事は法的ドキュメントであり、人間が判読できるソースを持っている必要があります。

それ以外の場合、サイト ポリシー コンテンツでは、GitHub Docs の残りの部分と同じスタイルとコンテンツモデルが使用されます。

ユーザー インターフェイスの要素

太字

操作可能な UI 要素を記述するには、太字を使います。

  • 左側のサイドバーで、 [課金] をクリックします。
  • pull request の [会話] タブの下部にあるマージ ボックス内を確認します。
  • [タイトル] の横に、新しいキーの説明ラベルを追加します。

ブランチ名

ブランチ名にはコードの書式設定を使います。

  • main
  • USERNAME.github.io

ボタン

ボタン名は太字で書式設定し、できるだけ "ボタン" という単語は省略します。 ボタンの使い方を説明するには、"プッシュ" や "押す" ではなく、"クリック" と書きます。

  • 以下を使います: [Pull request] をクリックします。
  • 以下は使いません: [Pull request] ボタンを押します。

チェック ボックス

チェック ボックス名は太字で書式設定し、"チェックボックス" という単語は省略します。 チェックボックスを選んだり解除したりすることについて説明するには、"選ぶ" または "選択解除" を使います。

  • 以下を使います: [すべての新しいリポジトリで有効にする] を選びます。
  • 以下は使いません: [すべての新しいリポジトリで有効にする] チェックボックスにチェックをオンにします。

動的テキスト

ユーザー インターフェイスで変化するテキストや、ユーザーがコマンドやコード スニペットに指定する必要があるテキストを示すには、大文字を使います。

  • 以下を使います: [USERNAME を REPONAME に追加] をクリックします。

リストとリスト アイテム

リストとクリック可能なリスト アイテムは太字で書式設定します。 ドロップダウン メニューや UI 要素などのリストを展開する操作について説明するには、リスト名が単語なのか octicon なのかに関わらず、"選ぶ" と書きます。 リスト アイテムの選択について説明するには、"クリック" と書きます。

  • 以下を使います: [バックアップ メール アドレス] ドロップダウン メニューを選び、 [プライマリ メールのみ許可] をクリックします。
  • 以下は使いません: [バックアップ メール アドレス] ドロップダウン メニューをクリックし、 [プライマリ メールのみ許可] をクリックします。

場所

ユーザー インターフェイス要素の場所は、標準的な用語を使って説明します。

  • の下、または、の上
  • の隣
  • 左上、右上、左下、右下
  • ページの上部、ページの下部、ページの右側、ページの左側

パネル

パネルは、できるだけ参照しないようにしてください。 代わりに、ユーザーが行う必要がある操作について説明します。

  • 以下を使います: リポジトリで [チャートとグラフを表示する] をクリックして、ドロップダウン メニューから表示する期間を選びます。
  • 以下は使いません: [チャートとグラフを表示する] をクリックして、選んだリポジトリのパネルを開いたら、ドロップダウン メニューから表示する期間を選びます。

UI に対する変更について説明したり、UI の操作方法について説明したりするためにパネルを参照する必要がある場合は、パネル名をユーザー インターフェイス テキストとして書式設定します。 単語パネルを含めるのは、これによりわかりやすくなる場合、または UI でパネルに名前が付けられていない場合のみです。

  • 以下を使います: [セキュリティ カバレッジ] パネルで、 [有効] または [無効] を選びます。
  • 以下を使います: パネルで、 [有効] または [無効] を選びます。

ラジオ ボタン

ラジオ ボタンのラベルは太字で書式設定し、"ラジオ ボタン" やその他の記述子は省略します。 ラジオ ボタンを使って説明するには、"選ぶ" と書きます。

リポジトリ名

バックティックを使用して固定スペース フォントでリポジトリ名のスタイルを設定します。 ユーザーがリポジトリに移動することが予想される場合、リポジトリへのリンクを指定します。

  • 使用: 詳細については、「github/docs」リポジトリを参照してください。

応答性の高い要素

あいまいさや混乱が生じた場合、UI 要素の応答状況のみを記録します。 応答性の高い UI 要素が原因でタスクが不明な場合、タスクの目標を達成するためにユーザーが行う必要がある対応について説明してください。 UI 要素の視覚的な状態のみを記述しないでください。

  • 使用方法:****[セキュリティ] をクリック。 [セキュリティ] が表示されない場合、[⋮] をクリックしてリポジトリ メニューを展開します。

ユーザー インターフェイスのテキスト

ユーザー インターフェイス内のテキストを参照する場合は、そのテキストを正確に再現します。 操作できない UI テキストを囲むには、引用符を使います。

  • 以下を使います: [IP 許可リスト] で、 [編集] をクリックします。

その他のリソース

Microsoft スタイル ガイド:

ビデオ

テキストベースの情報を補足するためにビデオを追加することはありますが、ビデオが書き物のコンテンツを取って代わることは決してありません。 ビデオは、一部のユーザーが利用できないうえに、検索しても見つけるのが困難です。

GitHub Docs Web サイトのビデオは、内容に優れており、障碍のあるユーザーにとって妨げとなるものが少なく、ビデオを対象とした GitHub のコンテンツ モデルに準拠している必要があります。 詳細については、GitHub Docs での動画の使用に関するページを参照してください。

ボイスとトーン

幅広い読者にとって親しみやすい、明確で簡潔な表現を使います。 信頼が置けるうえに、共感することができ、自信に満ちた文章を書きましょう。

対象ユーザーに向けて書いてください。専門用語や技術用語には、必要なものもありますが、すべての読者が同じレベルの技術的な専門知識を持っているという前提を当てにはしないでください。

可能な限り能動態を使用してください。 動作の目的を強調する必要がある場合には、受動態を使用します。

GitHub はグローバルな開発者コミュニティです。 特定の地域や国に特有の語句、慣用句、スラングは使わないようにしてください。

親しみやすいコンテンツの書き方について詳しくは、「Microsoft のブランド ボイス: 大切なのは簡潔さと人間味」と「Microsoft のスタイルとボイスのヒント Top 10」をご覧ください。

言葉の選び方と用語

一般的なガイダンスと GitHub 固有の用語については、「用語集」を参照してください。 詳しいガイダンスについては、Microsoft スタイル ガイドのA-Z 単語リストをご覧ください。

省略形

製品自体に対して明示的に短縮されている単語について言及する場合を除き、単語のスペルはすべて記してください。

  • 以下を使います: Repository (リポジトリ)
  • 以下は使いません: Repo (リポジトリ)
  • 以下を使います: Administrator (管理者)、管理者権限を持つユーザー
  • 以下は使いません: Admins (管理者)

GitHub のユーザー インターフェイスで使われていないシンボルや octicon は使わないでください。

  • 以下を使います: [ファイル] をクリックして、 [編集] をクリックします。
  • 以下は使いません: [ファイル] > [編集] をクリックします。

アカウント

製品名とアカウント

あいまいさと混乱を避けるために、製品名は、製品のアカウントを説明するための形容詞としては使わないでください。 代わりに、アカウントの種類を明確にするとともに、アカウントと製品が同一視されないような、はっきりとした言い回しを選んでください。 アカウントについて話すときに、製品間の違いを明確に示す必要がある場合は、製品名にのみ触れてください。 GitHub の製品で利用できるアカウントの種類の詳細については、「GitHub アカウントの種類」を参照してください。

  • 以下を使います: GitHub Enterprise Cloud 上の Organization
  • 以下は使いません: GitHub Enterprise Cloud アカウント
  • 以下は使いません: GitHub Enterprise Server Organization
  • 以下を使います: GitHub.com のプロフィールにコントリビューション数を送信すると、GitHub Enterprise Server で作業を強調表示できます。

GitHub の個々のユーザーのアカウント

個々のユーザーがコンテキストに応じてさまざまな方法でサインインするアカウントを指します。

Enterprise 製品の管理についてのコンテンツでない限り、GitHub の個々のユーザーのアカウントは、"個人用アカウント" として記述してください。 これにより、UI との一貫性が生まれ、同じことを意味する 2 つの用語を目にした読者の混乱を回避することができます。

  • 以下を使います: 個人アカウントのスケジュールされたリマインダーを管理する
  • 以下は使いません: ユーザー アカウントのスケジュールされたリマインダーを管理する

Enterprise 製品のアカウント

GitHub の Enterprise 製品では、管理者が Enterprise アカウントを管理できます。 Enterprise アカウントでは、複数の Organization を所有できることに加え、ユーザーのユーザー アカウントを Organization のメンバーにすることができます。 詳しくは、各製品についての「Enterprise でのロール」の記事をご覧ください。

読者が Enterprise アカウントを管理しており、あなたはユーザーが管理するユーザーのアカウントについて説明している場合は、"ユーザー アカウント" を使います。 これは、次の製品に適用されます。

  • Enterprise Managed Users がいる GitHub Enterprise Cloud
    • 以下を使います: Enterprise Managed Users については、Enterprise メンバーのユーザー アカウントを作成して管理できます。
    • 以下は使いません: Enterprise Managed Users については、Enterprise メンバーの個人用アカウントを作成して管理できます。
  • GitHub Enterprise Server
    • 以下を使います: ユーザー アカウントを一時的に引き継ぐ必要がある場合は...
    • 以下は使いません: 個人用アカウントを一時的に引き継ぐ必要がある場合は...

次のドキュメントでは、"ユーザー アカウント" と言及する必要があります。

Enterprise Managed Users を利用していない GitHub Enterprise Cloud の Enterprise については、その Enterprise が所有している Organization のメンバーについて説明する場合は、"個人用アカウント" を使います。

  • 以下を使います: SAML SSO を構成する場合、Organization のメンバーは、引き続き GitHub.com で個人用アカウントにサインインします。
  • 以下は使いません: SAML SSO を構成する場合、Organization のメンバーは、引き続き GitHub.com でユーザー アカウントにサインインします。

Enterprise Managed Users がいない GitHub Enterprise Cloud について説明しているドキュメントは、通常「Organization で SAML シングルサインオンを管理する」カテゴリにあります。

他のサービスでのユーザーのアカウント

統合プロバイダーや認証プロバイダーなど、GitHub 以外のサービスでのユーザーのアカウントについて説明する場合は、"ユーザー アカウント" を使います。

頭字語

タイトルやヘッダーを除き、記事内で頭字語を初めて使うときは、スペルをすべて記してください。

アプリ

一般的なコンテンツでは、"アプリ" または "アプリケーション" を使います。

  • 以下を使います: GitHub Marketplace でアプリを公開して一覧表示する

OAuth apps について言及する場合、これは製品ではないため、"アプリ" を使います。

  • 以下を使います: OAuth appを登録する
  • 以下は使いません: OAuth App を登録する

GitHub Apps について言及する場合、これは製品であるため、"App" を使います。

  • 以下を使います: GitHub App を登録する

GitHub Apps と OAuth appsは、アプリの登録と、アプリを動作させるコードという 2 つの部分から構成されています。

  • GitHub UI で単に GitHub App の設定や構成について言及するには、"登録" や "GitHub App の登録" のような用語を使います。

    • 以下を使います: GitHub App を登録する
    • 以下を使います: GitHub App の登録を更新する
    • 以下は使いません: GitHub App を作成する
    • 以下は使いません: GitHub App を変更する

  • 単にアプリのコードについて言及するには、"アプリ用のコード" や "アプリのコード" のような用語を使います。

    • 以下を使います: アプリ用のコード
    • 以下を使います: GitHub App のコード
    • 以下を使います: アプリのコード
    • 以下は使いません: GitHub App
    • 以下は使いません: OAuth app

  • アプリ全体 (登録とコード) についてまとめて言及するには、GitHub App、または OAuth appと呼んでください。

GitHub Apps は、Organization にも、ユーザー アカウントにもインストールされることがあります。 このアプリのインストールについて言及するには、"GitHub App" ではなく、"GitHub App のインストール" を使います。

Currency

ドル、セント、通貨の金額について言及する場合や $ 記号を使う場合は、金額がゼロであっても、使う通貨を必ず定義してください。 ISO の標準通貨名を使い、できるだけ ISO の標準通貨コードを使います。

通貨名には小文字を使います。ただし、国や地域を指す文字は大文字にします。

  • 以下を使います: US dollar (米ドル)。
  • 以下は使いません: US Dollar、$USD dollar (米ドル)。

通貨コードには大文字を使います。

  • 以下を使います: USD。

1 つの記事内で 1 回のみ言及する場合は、金額の前に $ 記号を付けずに通貨名を使います。

  • 以下を使います: 通貨について 1 回のみ言及する場合は、10 US dollars (10 米ドル) です。

1 つの記事内で同じ通貨について複数回言及する場合、1 回目の言及では、金額の前に $ 記号は付けず、通貨名を使い、通貨名の後に通貨コードをかっこに入れます。

1 つの記事内で通貨について 2 回以上言及する場合や適切な場合 (スペースを考慮する場合、テーブルまたはリスト内で複数の金額を提示する場合など) は、金額の前に $ 記号を付けて、金額の後に ISO の標準通貨コードを使います。

  • 以下を使います: 1 回目の言及では 10 US dollars (USD) (10 米ドル (USD))、2 回目以降は $0.25 USD ($0.25 USD)。
  • 以下は使いません: $10 US dollars (USD) ($10 米ドル (USD))、USD$0.25 (USD$0.25)。

1 回目の言及がセントやドル以外の金額についての場合は、1 回目の言及のすぐ後に、その通貨が使われている国や地域を大文字で示して、かっこに入れてください。 2 回以上言及する場合は、上記のガイドラインを使って処理してください。

  • 以下を使います: 1 回目の言及では 99 cents (US currency) (99 セント (米国の通貨))、2 回目以降は 99 cents (99 セント)。
  • 以下は使いません: $0.99 (US currency) ($0.99 (米国の通貨))、$0.99 USD cents ($0.99 USD セント)、USD$0.99 cents (USD$0.99 セント)。

アクセス許可

権限とは、特定のアクションを実行できる能力のことです。 たとえばIssueを削除する能力は権限です。

ロールとは、ユーザーに割り当てることができる一連の権限のことです。 ロールはさまざまなレベルに存在します。

  • アカウント (例: Organization オーナー、Enterprise アカウントの支払いマネージャー)
  • リソース(例: リポジトリ用に書き込みやセキュリティ アドバイザリの管理)
  • チーチーム(例: チーム メンテナ)

ユーザーのアクセス権とは、一般的に、そのユーザーが特定のコンテキストで持っているすべての能力を指します。それらの能力を、どのロール、またはどの個々の権限で取得したかは関係ありません。

これら 2 つの区別が重要な場合のみ、権限またはロールを使います。 それ以外の場合は、アクセス権を使います。

  • 以下を使います: カスタム リポジトリ ロールを作成するには、継承されたロールを選択し、個々のアクセス許可を追加します。
  • 以下を使います: Organization のリポジトリへのチーム アクセスの管理
  • 以下を使います: チーム メンバーシップによって、Organization の所有者としての役割とは異なるレベルのアクセス権が付与される場合...
  • 以下を使います: 書き込みアクセス権限を持つユーザーは...
  • 避けるべき事項: 書き込みアクセス権限を持つユーザーは...
  • 以下は使いません: 書き込みロールを持つユーザーは...
  • 以下は使いません: 書き込みアクセス許可を持つユーザーは...
  • 以下は使いません: 書き込み権限を持つユーザーは...

アクションを実行するために必要なアクセス権を指定する場合は、アクションと同じレベルのロールのみについて言及します。 たとえば、保護されたブランチを構成するには、リポジトリ、すなわちリポジトリ レベルのロールへの管理者アクセス権が必要です。 Organization レベルのロールである Organization オーナーであることによってリポジトリへの管理者アクセス権を取得できますが、実際は、アクションを実行するための能力はリポジトリ レベルのロールによって制御されるため、このロールのみを取り上げる必要があります。

  • 以下を使います: リポジトリへの書き込みアクセス権限を持つユーザーは、リポジトリに対して X を実行できます。
  • 以下は使いません: Organization の所有者と書き込みアクセス権限を持つユーザーは、リポジトリに対して X を実行できます。

アクセス許可ステートメントでの単語の選び方の詳細については、コンテンツ モデルの「GitHub Docs の記事の内容」を参照してください。

前置詞

書き直した文章が読みづらい、またはあまりにも堅苦しい場合を除き、文章が前置詞で終わらないようにしてください。

製品名

このガイドの「製品名」セクションをご覧ください。

使う用語と使わない用語

用途回避
個人ユーザー、お客様
terminalシェル
usernameログイン (login)
sign inログイン
サインアップサインアップ
推奨されている制限ソフト制限
email電子メール (e-mail)
frontmatterfront matter、front-matter
GitHub 上でリモート リポジトリ上で
(キーを) 押す打つ、タップする
入力する (ユーザー インターフェイスの場合)入力する (ユーザー インターフェイスの場合)
入力する (コマンド ラインの場合)入力する (コマンド ラインの場合)

単語の選択

あいまいな動詞

タスクが必要な場合、または別のオプションが優先される場合は、「かもしれない」、「すはずだ」、「可能性がある」などのあいまいな法助動詞の使用を避けてください。 これらの動詞は、命令または提案として解釈できます。 代わりに、アクションが必須かオプションであるかを明確に示す動詞を使用します。 あることがオプションまたは提案である場合は、アクションがオプションであることを明確にする限り、これらの動詞を使用できます。

  • 使用: 使用するキーボード ショートカットを決定できます。
  • 使用: リポジトリをクローンには、git clone コマンドを使用します。
  • 回避: リポジトリを複製には、git clone コマンドを使用できます。
  • 回避: ブランチを削除できるかもしれません。

不可視の複数形

不可視の複数形は、単数とも複数とも解釈されるため意味が曖昧になるため、使用を避けてください。 たとえば、"ファイルの取得" は、1 ファイルを取得する、あるいは複数ファイルを取得すると解釈できます。

  • 使用: そのファイルを取得したら、保存する場所を選択します。
  • 回避: ファイル取得の後、保存する場所を選択します。

名詞化

動詞または形容詞の名詞化は避けてください。 名詞化により、文が長くなり、理解しにくく、翻訳が困難になる可能性があります。

  • 使用: ワークフローが完了すると、パッケージが表示されます。
  • 回避: ワークフローが完了に達すると、パッケージが表示されます。

名詞の文字列

誤訳につながることがあるため、修飾語を続けて使わないようにしてください (名詞の文字列)。翻訳で、どの単語がどの単語を修飾しているかが伝わらない可能性があるからです。 名詞の文字列は、前置詞を使って言い換えることができます。 どうしても修飾語を続けて使う必要がある場合は、読者と翻訳者が被修飾語を把握できるように、背景情報とコンテキストを必ず明確にしてください。

  • 以下を使います: Default source settings for public repositories (パブリック リポジトリの既定のソース設定)
  • 以下は使いません: Public repository default source settings (パブリック リポジトリの既定のソース設定)

あいまいな名詞と代名詞

代名詞が複数の先行詞を指しているように思える場合は、先行詞を明確にするために文を書き換えるか、代名詞を名詞に置き換えてあいまいさを排除します。

  • 使用: ブランチに最終的なコミットを行い、pull request をマージした後、ブランチを削除できます。
  • 回避: ブランチに最終的なコミットを行い、pull request をマージした後、それを削除できます。

Footnotes

  1. Not to be confused with Davy Jones of The Monkees ↩

  2. Also humans ↩