GitHub Docs の記事の内容

記事の構造について

記事内には、コンテンツセクションの標準的な順序があります。すべての記事に必要な要素が含まれています。記事には、コンテンツのデザインまたは作成で概説されている条件付き要素と省略可能な要素も含まれます。詳しくは、以下のガイドラインを参照してください。

タイトル、概要、アクセス許可、製品吹き出し、概念セクション、手続き型セクション、目次のラベルが付いた記事のスクリーンショット。

タイトル

タイトルには、ページの概要と、ユーザーがそれを読んで学ぶ内容が完全に記述されています。

タイトルを付けるのは難しい場合があります。これらの一般的なガイドラインを使用すると、明確で有用なわかりやすいタイトルを作成するのに役立ちます。この記事の各コンテンツの種類のガイドラインでは、より具体的なタイトルルールが提供されます。

すべてのコンテンツの種類のタイトル

タイトルには、ページの概要が明確に記述されています。それらはわかりやすく明確です。
- 使用する: "ワークフローエディターでのアクションのブラウズ"
- 使用する: "codespace の構成例"
- 避ける: "ワークフローエディターのサイドバーの使用"
- 避ける: "例"
タイトルには、理解しやすく (またサイトでレンダリングしやすく) するために長さのハード制限があります。
- カテゴリのタイトル: 67 文字、shortTitle の場合 26 文字
- マップトピックのタイトル: 63 文字、shortTitle の場合 29 文字
- 記事のタイトル: 80 文字、可能な場合は 60 文字。shortTitle の場合 30 文字 (20 から 25 文字が好ましい)
タイトルでは、文の大文字と小文字が使用されます。
- 使用する: "コミットメッセージの変更"
- 避ける: "コミットメッセージの変更"
タイトルはコンテンツタイプ全体で一貫しています。各コンテンツタイプの特定のガイドラインを参照してください。
タイトルは、PRODUCT の変更点に合わせてスケーリングしたり、記事内のすべてのコンテンツを反映したり、複数の PRODUCT にコンテンツを含めたりするのに十分な全般的なものです。
- 推奨: 「GitHub の課金プラン」
- 避ける: 「ユーザーと Organization アカウントの課金プラン」
タイトルには一貫性のある用語が使用されます。
- カテゴリ内または類似性のあるサブジェクトのパターンを開発し、それをフォローします。
タイトルには PRODUCT 自体の用語が使用されます。
タイトルと概要を同時に書き込みます。
- 概要を使用して、タイトルに示されるアイデアを開発します。
- 詳しくは、概要に関するガイダンスを参照してください。
タイトルを考え出すのが難しい場合は、コンテンツの種類を検討してください。タイトルを選ぶのが難しい場合、別のコンテンツの種類の方が適していることがあります。
複数の PRODUCT の検索結果にタイトルがどのように表示されるかを考えます。
- ユーザーが別の製品に関するコンテンツと間違えないように、タイトルまたは概要に含める必要がある具体的な言葉は何ですか?
運用環境でのタイトルの外観について考えます。

イントロ

すべてのページの上部には、コンテキストを提供し、期待を抱かせる概要があり、閲覧者はページがそれらに関連しているかどうかをすばやく判断できます。また、概要は検索結果に表示され、閲覧者が結果を選ぶのに役立つコンテキスト情報が提供されます。

概要の記述方法

記事の概要は 1 から 2 文の長さです。
マップトピックとカテゴリの概要は 1 文の長さです。
API リファレンスの概要は 1 文の長さです。
- API ページの概要では、記事全体を読まずに機能が自分のニーズを満たしているかどうかがわかるように、機能を定義する必要があります。
概要には、タイトルに示されるアイデアをより詳細にするページのコンテンツの概要が含まれます。
- ページのタイトルにわかりやすい類義語を使用して、閲覧者が記事の目的を異なる方法で理解できるようにします。可能な場合は、タイトルの単語を繰り返さないようにします。
概要は比較的常に新しく大まかなものであるため、頻繁に更新しなくても、ページ上のコンテンツに対する将来の変更に合わせてスケーリングできます。
検索しやすくするために、概要にページの件名のキーワードを含めます。
概要の用語に頭字語があり、記事の他の場所で使用する場合は、その頭文字を示します。
一般に概要には、記事に含まれるタスクに対するアクセス許可は含まれません。

権限ステートメント

すべての手順には、その手順で説明されているアクションを実行するために必要なロールを説明するアクセス許可ステートメントが含まれています。これは、ユーザーがタスクを完了できるかどうかを理解するのに役立ちます。

場合によっては、概念コンテンツ (特にスタンドアロンの概念記事) で必要なアクセス許可の説明に関連します。関連手順にもアクセス許可ステートメントを必ず含めるようにしてください (または、すべてのコンテンツを組み合わせたより長い記事を記述してください)。

アクセス許可ステートメントを記述する方法

記事内のすべての手順に 1 つのアクセス許可セットが適用される場合は、permissions frontmatter を使用します。
記事に複数の手順が含まれており、異なるアクセス許可が適用される場合は、関連する各ヘッダーの下 (各手順の前) に個別のアクセス許可ステートメントを含めます。
記事の概要にアクセス許可を含めないでください。
ロールはさまざまなレベルに存在します。アクションと同じレベルのロールのみを参照してください。たとえば、保護されたブランチを構成するには、リポジトリ (リポジトリレベルのロール) への管理者アクセス権が必要です。 Organization 所有者 (Organization レベルのロール) であることでリポジトリへの管理者アクセス権を取得できますが、リポジトリレベルのロールによって実際にアクションを実行する能力が制御されるため、アクセス許可ステートメントで説明する必要がある唯一のロールです。
アクセス許可ステートメントで使用する言語:
- [アカウントロール] で [アクション] を実行できます。
- [機能] に対する [機能ロール] のアクセス権を持つユーザーは [アクション] を実行できます。
- 避ける: [アカウントロール] と [機能] に対する [機能ロール] のアクセス権を持つユーザーは [アクション] を実行できます。

アクセス許可ステートメントの例

複数の手順に対する 1 つのアクセス許可ステートメントを含む記事: Enterprise でリポジトリ管理ポリシーを適用する

製品吹き出し

製品吹き出しは、機能が特定の製品でのみ使用でき、バージョン管理だけでは可用性を伝えられない場合に使用します。たとえば、機能を GHEC と GHES で使用できる場合は、GHEC と GHES のみの機能に関するコンテンツをバージョン管理できます。機能を Pro、Team、GHEC、GHES で使用できる場合 (ただし、無料ではない)、製品吹き出しを使用してその可用性を伝えます。

すべての製品吹き出しは、gated-features に再利用可能なものとして格納され、関連する記事の YAML frontmatter に追加されます。

製品吹き出しの記述方法

製品吹き出しでは、厳密な形式に従い、機能とそれが利用可能な製品を明確に特定します。
製品吹き出しには、「GitHub の製品」へのリンクや、場合によっては別の関連記事へのリンクも含まれています。
例 :
- [機能名] は [製品] で使用できます。詳しくは、「GitHub の製品」を参照してください。
- [機能名] は、[無料の製品] を含むパブリックリポジトリ、および [有料製品] を含むパブリックとプライベートリポジトリで使用できます。詳しくは、「GitHub の製品」を参照してください。

製品吹き出しを含む記事の例

ソースファイルと gated-features を確認し、ソースコンテンツの記述方法を調べます。

ブランチ保護ルールを管理する

ツールスイッチャー

一部の記事には、GitHub CLI や GitHub Desktop など、タスクを完了するためにユーザーが使用するツールによって異なるコンテンツがあります。ほとんどのコンテンツでは、複数のツールに対して同じ概念または手順に関する情報が正確になります。ただし、ツールでコンテンツを区別するのが、情報を明確かつ正確にする唯一の方法である場合は、ツールスイッチャーを使用します。ツールスイッチャーは、さまざまな言語で例を表示するためだけに使用しないでください。ツールスイッチャーは、他のユーザーが使用するツールに基づいてタスクまたは概念が変わる場合にのみ使用します。詳しくは、「記事でのツールスイッチャーの作成」をご覧ください。

概念的コンテンツ

概念コンテンツは、ユーザーがトピックについて理解または学習するのに役立ちます。詳しくは、コンテンツモデルの「概念的コンテンツタイプ」をご覧ください。

参照コンテンツ

参照コンテンツでは、製品または機能の積極的な使用に関連する構造化された情報が提供されます。詳しくは、コンテンツモデルの「参照コンテンツタイプ」をご覧ください。

前提条件

前提条件は、ユーザーがタスクを開始する前に必要なものをすべて準備できるように、手順を進める前に知っておく必要がある情報です。

前提条件を記述する方法

番号付き手順の直前に前提条件を記述します。
リスト、文、または段落を使用して、前提条件を説明できます。
次の場合は、別の前提条件セクションを使用することもできます。
- 前提条件の情報は非常に重要です。見逃さないようにしてください。
- 複数の前提条件があります。
データ損失や破壊的なアクションに関する重要な情報を繰り返したり、強調するために、警告または危険という吹き出しを使用して前提条件を共有することもできます。

前提条件のタイトルガイドライン

別のセクションを使用する場合は、Prerequisites というヘッダーを使用します

前提条件セクションを含む記事の例

手続き型コンテンツ

手続き型コンテンツは、ユーザーがタスクを完了するのに役立ちます。詳しくは、コンテンツモデルの「手続き型コンテンツタイプ」をご覧ください。

トラブルシューティングコンテンツ

トラブルシューティングコンテンツは、ユーザーがエラーを回避または処理するのに役立ちます。詳しくは、コンテンツモデルの「トラブルシューティングコンテンツタイプ」をご覧ください。

次のステップ

記事で大規模なプロセスの 1 つのステップについて説明する場合、またはほとんどのユーザーが行う必要がある論理的な次のステップがある場合は、次のステップセクションを含めます。ユーザーを記事やその他の GitHub リソースにリンクできます。

次のステップセクションの例

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

「企業向けセルフホストランナーの概要」のこの例では、「次の手順」セクションに、記事で説明されている機能の使用を開始した後に実行する必要がある手順へのリンクが含まれています。

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

「Enterprise アカウントの作成」のこの例では、次のステップは、Enterprise アカウントの作成を完了したほとんどのユーザーが次に進む必要がある場所にリンクします。

参考資料

ユーザーがタスクを完了したり、現在の記事で説明されているトピックの使用を学習したりするのに役立つその他の記事がある場合は、参考資料セクションに含めてください。記事のコンテンツ内にまだリンクされていない記事へのリンクのみを含めます。

タスクまたはトピックを持つユーザーに役立つリンクのみを含めます。すべての可能なリンクを提供するよりも、焦点を絞って貴重なリソースをユーザーに提供することをお勧めします。

順序付けされていないリストを使用して、参考資料セクションの形式の設定を行います。リンクの記述方法については、「スタイルガイド」をご覧ください。

参考資料セクションのタイトルと形式

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name

GitHub Docs の記事の内容

この記事の内容