ほとんどのパッケージは、ユーザーが最高の体験をし、使用を最適化できるように、何らかの形で説明が必要です。このページでは、情報の構成 と ドキュメントの形式 についてのヒントを紹介します。
パッケージのタイトルの後には、そのパッケージの用途や何が含まれているのかという基本的な概要を述べます。概要に続いて、インストール方法、システム要件、制限事項などを記載します。また、公開フォーラムやナレッジベース、ヘルプデスクの連絡先など、ヘルプやフィードバックを得るためのリンクを提供します。
このような予備的な情報の後に、より詳細なワークフロー、ユーザーインターフェースやサンプルのディレクトリリストの説明、そしてより高度なトピックについて説明します。最後に参考資料を紹介すると良いでしょう。
| セクション | 説明 |
|---|---|
| Overview (概要) | パッケージの概要を簡潔に説明してください。 |
| Package contents (パッケージ内容) | ユーザーに把握してほしい重要なファイルの場所を記載します。例えば、サンプルパッケージの場合、テクスチャ、モデル、マテリアルがサンプルグループごとに分けてあれば、各グループのフォルダーの場所を記載するとよいでしょう。 |
| Installation instructions (インストール方法) | 公式の Package Manager インストール手順 を紹介することができますが、サンプルのインストールなど特別なインストール要件がある場合は、ここに記載してください。 |
| Requirements (要件) | このパッケージがどのバージョンの Unity エディターに対応しているかなど、ハードウェアやソフトウェアの要件の説明すに適した場所です。 |
| Limitations (制限事項) | パッケージに既知の制限がある場合、それをここに記載します。そうでない場合、または制限が些細なものである場合は、このセクションは除外できます。 |
| Workflows (ワークフロー) | ユーザーが簡単にたどれるように一連の手順を記載し、その機能の使い方を示してください。機能の使い方を分かりやすくするためにスクリーンショットを加えることができます。 |
| Advanced topics (高度なトピック) | ここでは、ユーザーに提供している機能について、詳細な情報を説明します。この項目を使って、必要以上に多くの情報を提供することを避けることができます。 |
| Reference (参照) | 多くのプロパティを持つユーザーインターフェースがある場合は、参照セクションで詳細を提供することができます。テーブルを使用すると、特定のプロパティの説明に素早くアクセスできます。 |
| Samples (サンプル) | サンプルファイルが含まれているパッケージでは、ユーザーがプロジェクトやシーンでこれらのサンプルファイルをどのように使用できるかについての詳細な情報を含めることができます。 |
| Tutorials (チュートリアル) | 複雑な手順のウォークスルーを提供したい場合は、ここに加えることもできます。ユーザーによりわかりやすくするために 1 つ 1 つ順を追って説明し、画像を加えると良いでしょう。 |
Markdown (マークダウン) は、パッケージでよく使われる軽量記法です。多くのリポジトリホスティングサービス (GitHub や Bitbucket など) で、README やドキュメントサイト用にサポートされています。パッケージルートの下にある Documentation~ フォルダーに MD ファイルを提供することで、ユーザーが Unity の Package Manager の詳細ペインにある View documentation リンクをクリックすると、ユーザーのデフォルトの MD ビューアーがそのファイルを開きます。
または、独自のウェブサイトを使用してドキュメントをホストすることもできます。View documentation (ドキュメントの表示) リンクの場所を自分のウェブサイトを指すように設定するには、package.json ファイルの documentationUrl プロパティを使用して設定します。
パッケージのドキュメントに Markdown ファイルを使う場合は、MD ファイルの書き方についてのより詳しい情報は、数多くのヘルプサイトから見つけることができます。以下はその一例です。