すべての製品のドキュメントは同じ核となるセクションから構築します。ある製品のドキュメントを知っている読者が、別の製品でも探し場所を予測できるようにするためです。
一貫性は任意ではなく、強制します。製品が本当に必要なセクションを追加することはできますが、その追加は核への加算です。別の形のほうが「その製品には合う」からといって、核となるセクションの名前変更、再構成、再定義はしません。核は同じまま、周囲に広げます。
このページは、セクション（フォルダー）レベルの共有核を定義します。個別ページの種類を選ぶには、コンテンツタイプ を参照してください。
すべての製品は、初回リリースから少なくとも次の 2 ページを含みます。
- Overview — 新規読者を案内し、次の行き先へ誘導します。
- Get started — 新規ユーザーをゼロから最初の動作結果まで連れていきます。
必須の 2 ページに加え、製品に該当するコンテンツがあるときは、次の標準セクションを使います。標準名を使うと、読者とエージェントがすべての製品ドキュメントを同じ方法でナビゲートできます。
| セクション | 含む内容 | 関連するコンテンツタイプ |
|---|---|---|
| Overview | 新規読者を製品へ案内し、次の行き先へ誘導します。必須。 | Overview |
| Get started | ゼロから最初の動作結果までの最短経路です。必須。 | Get started |
| Concepts | 製品の主要な考え方と、その動きの理由です。 | Concept |
| Features | 製品の主要機能向けのタスクと設定コンテンツをまとめます。 | How to |
| Guides | 1 つの具体的な作業を完了するためのタスク中心のページです。 | How to |
| Tutorials | 読者が実際のプロジェクトを構築するエンドツーエンドのレッスンです。 | Tutorial |
| Examples | やり方を示す、完結して実行可能なサンプルです。 | なし |
| Configuration | 設定の多い機能向けの設定、値、オプションです。 | Configuration |
| Reference | パラメーター、値、オプションなどの、完結した中立の参照情報です。 | Reference |
| API | 製品の API ドキュメントとコマンドの案内です。 | API content strategy |
| Models | AI 製品向けの利用可能なモデルとその詳細です。 | Reference |
| Observability | テスト、メトリクス、アナリティクス、ローカル開発です。 | なし |
| Best practices | 製品をうまく使うための推奨パターンと指針です。 | なし |
| Platform | 料金、上限、changelog、ベータ、既知の問題など、製品全体のページです。 | Changelog |
| Glossary | 製品の定義済み用語です。 | Glossary |
- Overview は製品ルートの
index.mdxに置きます。その他の核となるセクションは、ページが 1 つでもフォルダーにします。単独のget-started.mdxはget-started/フォルダーにします。 - 核となるフォルダーは、製品固有のフォルダーより前に、核となるセクション の順で置きます。
- すべての製品に、少なくとも 1 ページを持つ Platform フォルダーを置きます。一部の製品にだけある状態ではなく、このセクションを一貫して存在させます。
- 製品固有のフォルダーには、一意でわかりやすい名前を付けます。製品固有のフォルダーは加算です。核に追加するものであり、核となるセクションの置き換えや形の変更はしません。
- セクションは自由に追加できますが、核は編集しないでください。核となるセクションが製品に合わない場合は、ローカルで名前変更や再構成せず、docs governance を通じて提起します。
製品を核と照合して監査し、ギャップを埋めます。
- 非標準のフォルダーを標準名にリネームします。たとえば
getting-startedフォルダーをget-startedに、how-toフォルダーを標準のguidesにします。 - ばらばらのファイルを核となるフォルダーにまとめます。単独の
concepts.mdxはconcepts/フォルダーにします。 platform/の中にあるが核となるセクションに属するコンテンツは、トップレベルへ引き上げます。- 製品に欠けている核となるセクションを作成します。
- 有用な製品固有フォルダーは残し、それぞれが一意の名前で加算であることを確認します。
核は Compute、Storage、AI、Media、垂直製品を含む、すべての製品カテゴリに適用されます。カテゴリは、その製品がすべて必要とする追加セクションを共有できます。たとえば、AI 製品は Models セクションをよく追加します。製品が成熟しても核は同じままです。核を作り直すのではなく、セクションを追加して広げます。