新規ドキュメントの追加

約5分

Istioに新しいドキュメントを投稿するには、以下の手順に従ってください。

情報の対象読者と目的を特定します。
貢献したいコンテンツの種類を選択してください。
タイトルを選択してください.
当社のドキュメント寄稿ガイドに従って、ご寄稿ください。
ご寄稿をGitHubリポジトリに提出してください。
ご寄稿がマージされるまで、当社のレビュープロセスに従ってください。

対象読者と目的の特定

最高のドキュメントは、対象読者、彼らの知識、そして彼らに情報をどのように活用してほしいかを理解することから始まります。そうでなければ、提供する情報の適切な範囲と深さ、理想的な構造、必要な補足情報を決定することはできません。次の例はこの原則を実践で示しています。

読者が特定のタスクを実行する必要がある場合：タスクが必要な状況を認識する方法を伝え、タスク自体を番号付きの手順のリストとして提供します。タスクを一般的な言葉で説明するだけではありません。
読者がタスクを実行する前に概念を理解する必要がある場合：タスクの前に、前提となる情報を伝え、そのリンクを提供します。
読者が意思決定をする必要がある場合：意思決定を行うための必要な概念情報を提供し、利用可能なオプションと、あるオプションを別のオプションの代わりに選択する場合を示します。
読者が管理者だがソフトウェアエンジニアではない場合：開発者ガイドのコードサンプルへのリンクではなく、スクリプトを提供します。
読者が製品の機能を拡張する必要がある場合：説明のために簡略化されたシナリオを使用して、機能を拡張する方法の例を提供します。
読者が複雑な機能間の関係を理解する必要がある場合：複数のページにわたる退屈な読み書きの内容ではなく、関係を示す図を提供します。

最も重要なことは、読者が何を求めているか分からずに、自分が持っている情報をすべて読者に提供するというよくある間違いを避けることです。

コンテンツの対象読者の特定にヘルプが必要な場合は、喜んでお手伝いし、ドキュメントワーキンググループの隔週ミーティングで皆様のご質問にお答えします。

コンテンツの種類

提供する情報の対象読者と目的を理解すれば、ニーズに最適なコンテンツタイプを選択できます。選択を容易にするために、次の表は、サポートされているコンテンツタイプ、対象読者、および各タイプが達成しようとする目標を示しています。

コンテンツタイプ	目標	対象読者
概念	Istioの重要な側面を説明します。たとえば、概念ページでは、機能の構成モデルを説明し、その機能を説明します。概念ページには、手順のシーケンスは含まれていません。代わりに、対応するタスクへのリンクを提供します。	プロジェクトの基本的な知識しか持たない読者で、機能の仕組みを理解したいと考えている人。
リファレンスページ	網羅的で詳細な技術情報を提供します。一般的な例としては、APIパラメータ、コマンドラインオプション、設定、高度な手順などがあります。リファレンスコンテンツはIstioコードベースから生成され、正確性がテストされています。	プロジェクトに関する高度で深い技術知識を持ち、高度なタスクを完了するために特定の情報ビットを必要とする読者。
例	一連の機能、Istioと他のプロジェクトの統合、またはユースケースのエンドツーエンドソリューションを強調する、動作するスタンドアロンの例を説明します。例は、既存のIstioセットアップを起点として使用する必要があります。例は、技術的な正確性の維持のために自動テストを含める必要があります。	例を自分で実行して実験したい読者。理想的には、読者は自分のソリューションを作成するために例を簡単に変更できる必要があります。
タスク	Istio機能を使用して単一の目標を達成する方法を示します。タスクには、手順のシーケンスとして記述された手順が含まれています。タスクは機能の説明を最小限に抑えますが、関連する背景と知識を提供する概念へのリンクを含めます。タスクは、技術的な正確性のテストと維持のために自動テストを含める必要があります。	Istio機能を使用したい読者。
セットアップページ	Istioの展開を完了するために必要なインストール手順に焦点を当てています。セットアップページは、技術的な正確性のテストと維持のために自動テストを含める必要があります。	展開を完了したい新規および既存のIstioユーザー。
ブログ投稿	Istioまたはそれに関連する製品とテクノロジーに焦点を当てています。ブログ投稿は、次の3つのカテゴリのいずれかに分類されます。 Istioの使用と設定に関する著者の経験を詳述した投稿、特に新しい経験や視点が明確に示されている投稿。 Istioの機能を強調する投稿。 Istioを使用してタスクを完了したり、特定のユースケースを実現したりする方法を詳述した投稿。タスクや例とは異なり、ブログ投稿の技術的な正確性は公開後に維持およびテストされません。	プロジェクトの基本的な理解があり、逸話的、経験的、そしてより非公式な方法でプロジェクトについて学びたい読者。
ニュースエントリ	Istioおよび関連イベントに関するタイムリーな情報に焦点を当てています。ニュースエントリは通常、新しいリリースまたは今後のイベントを発表します。	Istioコミュニティの最新情報と出来事をすばやく知りたい読者。
FAQエントリ	一般的な質問への簡単な回答を提供します。回答では、概念は導入されません。代わりに、実践的なアドバイスや洞察を提供します。読者が詳細を学ぶために、ドキュメント内のタスク、概念、または例へのリンクを付ける必要があります。	具体的な質問があり、簡潔な回答と詳細を学ぶためのリソースを探している読者。
運用ガイド	実世界の環境でIstioを実行しているときに発生する特定の問題に対処する実践的なソリューションに焦点を当てています。	Istio展開の実行に関する問題を解決したり、ソリューションを実装したいサービスメッシュオペレーター。

タイトルの選択

検索エンジンが検索するキーワードを含む、トピックのタイトルを選択してください。Istioのすべてのコンテンツファイルは`index.md`という名前ですが、各コンテンツファイルは、トピックのタイトルのキーワードを使用して名前が付けられたフォルダー内にあり、ハイフンで区切られ、すべて小文字です。クロスリファレンスの作成と保守を容易にするために、フォルダー名はできるだけ短くしてください。

GitHubへの貢献の提出

GitHubに慣れていない場合は、GitHubでの作業ガイドを参照して、ドキュメントの変更を提出する方法を学んでください。

貢献がいつどのように公開されるかについてさらに知りたい場合は、ブランチに関するセクションを参照して、ブランチとチェリーピッキングをコンテンツの公開にどのように使用するかを理解してください。