他の記事では、参照記事と参照セクションを作成します。
- 特に、GitHub Actions の検索構文や YAML 構文など、大量の参照コンテンツがある場合は、一部の主要な件名に独自の参照記事が必要になることがあります。
- コンテンツの量が少ないか、より具体的な情報の場合 (機能でサポートされている言語やハードウェア要件のリストなど) は、手続き型または概念記事内のコンテキストで参照セクションを使用します。
参照コンテンツを記述する方法
参照コンテンツ テンプレートについては、「テンプレート」を参照してください。
- 参照コンテンツを紹介するために、文または概念セクション全体を記述します。
- 実際の参照コンテンツを明確かつ一貫して示します。
- 説明する要素が 1 つの件名の場合は、リストを使用します。
- 説明する要素が複数ある件名の場合は、テーブルを使用します。
- ワークフローの YAML 構文など、より長い参照コンテンツの場合は、ヘッダーを一貫して使用します。
- 個別セクションの H2 ヘッダー。
- 例などのサブセクションの H3 ヘッダー。
- 例: GitHub Actions のワークフロー構文
参照コンテンツのタイトル
- 参照記事または参照セクションのヘッダーは、セクションのコンテンツを明確に記述するものであり、一般に名詞で始まります。
- タイトルには、初心者ユーザーがアクセスできる十分な情報が含まれており、各セクションのコンテンツが完全に記述されます。
- タイトルに複数の名詞を並べないでください。前置詞を使用して、名詞の長い文字列を分割します。
参照コンテンツの例
- 参照記事
- キーボード ショートカット
- エンタープライズにおける役割
- REST API ドキュメントの「請求の REST API エンドポイント」
- GraphQL API ドキュメントの「ミューテーション」
- 他の記事内の参照セクション
- 「GitHub Mobile」の「サポートされている言語」
- 「AWS で GitHub Enterprise Server をインストールする」の「ハードウェアに関する考慮事項」