コンテンツ モデルでは、GitHub Docs 内に作成するコンテンツの各種類の目的と、記事を記述または更新するときに含める内容について説明します。 コンテンツ モデルを使用して、当社のコンテンツによって、GitHub でユーザーが目標を達成するために必要な情報を一貫して、明確かつ包括的に伝えられることを確かめます。
すべてのドキュメント セットでこれらの種類を使用して、一貫したユーザー エクスペリエンスを提供します。すべてのコンテンツの種類は、すべての製品または対象ユーザーに適用されます。 コンテンツの種類は時間の経過と共に進化し、新しい種類が追加されます。 モデルに従うコンテンツのみを公開します。
一貫性は、ドキュメントのメンタル モデルを形成し、時間の経過に伴って GitHub Docs に戻る際に必要な情報を見つける方法を理解するのに役立ちます。 また、一貫性のあるコンテンツを維持および更新する方が効率的であり、初めてコミットを行うオープンソース共同作成者でも、新しい製品全体を文書化する GitHub スタッフのライターであっても、ドキュメントへの投稿がより簡単かつ迅速になります。
コンテンツの構造
ドキュメントは、サイト上の階層の複数のレベルに編成されています。
- 最上位のドキュメント セット
- Categories
- マップ トピック
- 記事
- 記事
- マップ トピック
- 記事
- Categories
コンテンツの整理とは、検索対象を見つけるのに役立つ特定のグループ化を作成することと、ユーザーが移動する必要がある階層のレイヤを制限することのバランスです。 多くのマップ トピックが入れ子になった複雑な階層では、特定の記事を見つけることが難しくなります。 多くのカテゴリまたは記事が同じレベルの幅広い階層では、ユーザーが選択する内容を評価して決定することが難しくなります。
ホームページのコンテンツ
GitHub Docs のホームページである docs.github.com では、ユーザーが見つけたい最も重要なトピックが強調表示されています。 ホームページのドキュメント セットの数を制限して、ユーザーが情報を見つけることができ、ホームページが過密になって検索が困難にならないようにします。
ホームページには、すべての最上位ドキュメントセットといくつかのカテゴリが含まれています。 ホームページ上のコンテンツは、GitHub の概念とプラクティスを中心に編成されています。 たとえば、「CI/CD と DevOps」グループには、GitHub Actions、GitHub Packages、GitHub Pages の最上位のドキュメント セットが含まれています。
ホームページへのドキュメント セットの追加
ホームページの目的は、ユーザーが知りたい GitHub 機能または製品に関する情報を見つけられるようにすることです。 ホームページに項目を追加するたびに、他の項目が見つけにくくなるため、ホームページに含まれるドキュメント セットの数を制限します。
新しい最上位ドキュメント セットが作成されると、ホームページにそれが追加されます。
カテゴリが GitHub 製品または機能を使用する開始点として機能する場合は、それをホームページに追加できます。
たとえば、ホームページの「セキュリティ」グループの下には、「コード セキュリティ」という最上位ドキュメント セットに加えて、「サプライ チェーンのセキュリティ」、「セキュリティ アドバイザリ」、「Dependabot」、「Code scanning」、「Secret scanning」というカテゴリが含まれます。これらの各カテゴリは GitHub 製品と機能へのエントリ ポイントであるためです。 「セキュリティの概要」は、コード セキュリティ製品を使用するための追加情報が提供され、製品や機能の概要ではないので、ホームページには含まれていません。
最上位のドキュメント セット
最上位ドキュメント セットは、GitHub 製品、機能、またはコア ワークフローを中心に編成されています。 すべての最上位ドキュメント セットは、GitHub Docs ホームページに表示されます。 最上位ドキュメント セットを作成するのは、新しいドキュメント セットに含まれるコンテンツが大量で、マップ トピックに分割された複数のカテゴリがあり、そのトピックが製品、機能、またはアカウントの種類にまたがって適用される場合のみです。 コンテンツが既存の最上位ドキュメント セットに収まる場合は、その既存のドキュメント セットに属している可能性があります。
- 各最上位ドキュメント セットの重要度はほぼ同じです (それぞれの GitHub 製品または主要な機能が中心となっています)。
- 重要な例外がない限り、ほとんどの最上位ドキュメント セットにはランディング ページ レイアウトがあります。 たとえば、「サイト ポリシー」ドキュメント セットには、他のドキュメント セットのようなガイドや手続き型の記事がないため、ランディング ページ レイアウトは使用されません。
- 最上位のドキュメント セットには、カテゴリ、マップ トピック、または記事の組み合わせを含めることができます。
最上位ドキュメント セットのタイトル
- 機能または製品ベース。
- 誰かが使用している GitHub の部分が記述されます。
- 例
カテゴリ
カテゴリは、製品のテーマに合わせて最上位ドキュメント セット内の機能または個別のタスク セットを中心に編成されます。 カテゴリの件名は、そのコンテンツを管理でき、大きすぎて使用できなくならない程度に範囲が絞られています。 一部のカテゴリはホームページに表示されます。
- 多くの場合、カテゴリは最初は小さく、製品と共に大きくなります。
- カテゴリには、より具体的なユーザー体験やタスクに関するコンテンツを分割するためのマップ トピックが含まれる場合があります。
- 長い手続き型記事を使用して、関連するコンテンツのチャンクをグループ化し、カテゴリ内の記事を合理化した状態に保ちます。
- カテゴリに 10 件を超える記事がある場合は、コンテンツをマップ トピックまたは追加のカテゴリに分割することを検討してください。
- カテゴリには、マップ トピックまたは記事の組み合わせを含めることができます。
カテゴリのタイトル
- タスク ベース (動名詞で始まる)。
- 機能または製品を使用する全体的な目的または目標を記述します。
- 将来の製品の機能強化に合わせてスケーリングするのに十分な一般的または大まかなもの。
- カテゴリ タイトルは 67 文字以下で、
shortTitleが 27 文字未満である必要があります。 - 例
カテゴリの概要
すべてのカテゴリに概要があります。 概要は、1 文の長さで、将来の製品の変更に合わせてスケーリングするのに十分な一般的または大まかなものである必要があります。 カテゴリの構造を大幅に変更する場合は、必要な更新の概要を確認してください。
マップ トピック
マップ トピックでは、カテゴリのセクションを紹介し、カテゴリのより大きなタスクの一部であるより具体的なワークフローまたは件名に関するカテゴリ内の記事をグループ化します。
マップ トピックには、少なくとも 2 つの記事が含まれています。 マップ トピックに 8 件を超える記事がある場合は、コンテンツをより具体的なマップ トピックに分割することを検討すると便利な場合があります。
一般に、特定のユーザーのニーズを満たす最善の方法でない限り、マップ トピック内にマップ トピックを含めないでください。
マップ トピックのタイトル
- タスク ベース (動名詞で始まる)。
- カテゴリのより大きなワークフロー内のより具体的なタスクを記述します。
- 製品への将来の追加に合わせてスケーリングするのに十分な一般的または大まかなもの。
- マップ トピックのタイトルは 63 文字以下で、
shortTitleが 30 文字未満である必要があります。 - 例
マップ トピックの概要
すべてのマップ トピックに概要があります。 概要は、1 文の長さで、将来の製品の変更に合わせてスケーリングするのに十分な一般的または大まかなものである必要があります。 マップ トピックで記事を追加または削除する場合は、必要な更新の概要を確認してください。
[アーティクル]
記事は GitHub Docs のコンテンツの基本的な単位です。複数のコンテンツの種類を使用していますが、これらはすべて記事として公開されます。 各コンテンツの種類には独自の目的、形式、構造があります。しかし、記事で一貫したユーザー エクスペリエンスを確実に提供できるように、概要などのすべての記事の種類で標準的な要素を使用します。
コンテンツの順序
カテゴリ、マップ トピック、記事内で予測どおりにコンテンツを整理します。 最も広い適用性から、最も具体的な、範囲を絞った、または詳細な情報まで、次の順序に従います。
- 概念的コンテンツ
- 参照コンテンツ
- 機能または設定を有効にするための手続き型コンテンツ
- 機能の使用に関する手続き型コンテンツ
- 機能または設定の管理に関する手続き型コンテンツ
- 機能または設定の無効化に関する手続き型コンテンツ
- 破壊的なアクションに関する手続き型コンテンツ (削除など)
- トラブルシューティング情報
コンテンツの再利用
再利用可能な変数文字列を使って、手続き型手順や概念的な段落など、同じコンテンツのチャンクを複数の場所で使用します。 一般に、具体的な理由なしに記事の大きなセクションを再利用することはありません。 記事のセクション全体が複数の記事に関連している可能性がある場合は、両方の目的を確認してください。 1 つの長い形式の記事を作成する機会はありますか? 情報に最適で永続的なホームを明確にし、他の記事からリンクするには、コンテンツ モデルを参照してください。