スタイル ガイド

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

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

監査ログのイベント

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

• セキュリティ ログのイベント
• Organization の監査ログ イベント
• 企業向け監査ログイベントのGitHub Enterprise Cloudドキュメント

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

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

警告

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

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

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

アラートのタイプ

注意、ヒント、重要、警告、注意という 5 種類のアラートを使っています。

注意

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

説明されているプロセスの中核ではない、注釈的な情報を伝える際に、ノートは特に役立ちます。

• 特定のユーザー設定など、プロセスの結果に影響する可能性がある注意事項。
• パブリック プレビューや閉鎖など、可用性の変更の対象となる製品と機能。

たとえば、 シークレット スキャンからのアラートの評価 はメモを使用して、 GitHub トークンのメタデータが現在 パブリック プレビューされていることをユーザーに通知します。

ヒント

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

たとえば、「AUTOTITLE」 がヒント アラートを使用すると、組織を @mention する際にユーザーが想定しておくべきことを把握するのに役立ちます。

重要

ユーザーが目標を達成するために知っておく必要がある重要な情報を強調します。

警告

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

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

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

注意事項

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

通常、警告は、コマンド ラインや 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 の使用」の「アラート」を参照してください。

再利用可能なテキストでアラートを使用する

アラートは、再利用可能なコンテンツの一部として頻繁に形成されます ( 再利用可能なコンテンツの作成 を参照)。

再利用可能な Markdown ファイル内にアラート環境を配置するのではなく、アラート環境内で再利用可能なコンテンツを呼び出します。

次に例を示します。

> [!CAUTION]
> {% data reusables.foo.bar %}
> Here is some additional optional text.

行動を促す呼びかけ

CTA とは、ユーザーに体験の次の手順に進むように促すリンクまたはボタンです。 ユーザーは別の場所に送信されます。

CTA の重要な要素は、ユーザーを次の手順に誘導したり、必要な製品や機能に誘導したりすることで、ユーザーが実行しようとしていたことを完了できるように支援することです。

CTA をいつ使うかを検討するときには、次の質問を検討してください。

• ユーザーにとって論理的なまたは必要な次の手順はありますか? たとえば、次に必要になる情報、タスクの達成に役立つ機能などです。
• ユーザーをその場所に送信するビジネス ニーズはありますか?

CTA は、両方の質問に対する答えが "はい"にのみ使う必要があります。

CTA とリンクの違い

CTA は、"Copilot を無料で試す" や "独自のリポジトリを作成する" など、すぐに行動を起こすようにユーザーに明確に指示するものです。 ドキュメント内の CTA は、ユーザーを GitHub所有ドメインにのみ誘導する必要があります。

たとえば、GitHub Enterprise Cloud の試用版の設定 の CTA は、のGitHub.comにリンクします。

CTA の構築

正しいパラメーターを使用して有効な CTA URL を作成するには、ドキュメント リポジトリのチェックアウトで CTA ビルダー スクリプトを使用します。

npm run cta-builder

このスクリプトでは、次の操作を行う対話型プロセスについて説明します。

• 適切な GitHub 製品を選択します (ref_product)
  • リンクが特定の機能または製品に固有でない場合は、 github を既定値として使用します
• アクションの種類を選択する (ref_type)
• 書式設定スタイルを指定する (ref_style)
• 必要に応じて、特定のプランを選択します (ref_plan)

このスクリプトは、各パラメーターに使用可能なすべてのオプションを提供し、最後に完全で有効な CTA URL を生成します。 このツールを使用して、CTA パラメーターの現在の承認済み値を使用していることを確認します。

たとえば、スクリプトによって次のような URL が生成される場合があります。

https://github.com/account/enterprises/new?ref_product=ghec&ref_type=trial&ref_style=button&ref_plan=enterprise

Code

コード ブロック

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

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

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

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

• ユーザーが置換する必要があるプレースホルダーは、すべて大文字でスタイル設定します。

  • 以下を使います: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:
  -