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