Большинство пакетов нуждаются в некотором объяснении, чтобы помочь пользователям получить наилучшие впечатления и оптимизировать их использование. На этой странице приведены некоторые советы по структурированию информации и формат документации.
Структура информации
После названия пакета вы должны дать общий обзор того, что пакет делает и/или что он содержит. После обзора включите инструкции по установке, а также любые системные требования и/или ограничения. Вы также можете предоставить ссылки для получения помощи и обратной связи, в том числе общедоступные форумы или базы знаний, а также контакты службы поддержки.
После этой предварительной информации вы можете предоставить более подробные рабочие процессы, описание пользовательского интерфейса или списки каталогов для образцов, а затем более сложные темы. Справочные страницы лучше размещать ближе к концу.
| Раздел | Описание |
|---|---|
| Overview | Дайте краткое, высокоуровневое объяснение пакета. |
| Package contents | Включите расположение важных файлов, о которых вы хотите, чтобы пользователь знал. Например, если это образец пакета, содержащий текстуры, модели и материалы, разделенные по группам образцов, вы можете указать расположение папки для каждой группы. |
| Installation instructions | Вы можете указать официальные инструкции по установке диспетчера пакетов, но если у вас есть особые Требования к установке, такие как установка образцов, добавьте их сюда. |
| Requirements | Это хорошее место для добавления требований к оборудованию или программному обеспечению, включая версии редактора Unity, с которыми совместим этот пакет.. |
| Limitations | Если у вашего пакета есть какие-либо известные ограничения, вы можете перечислить их здесь. Если нет или если ограничения тривиальны, исключите этот раздел. |
| Workflows | Включите список шагов, которые пользователь может легко выполнить, демонстрирующих, как использовать эту функцию. Вы можете включить снимки экрана, чтобы описать, как использовать эту функцию. |
| Advanced topics | Здесь вы можете предоставить подробную информацию о том, что вы предоставляете пользователям. Это идеально, если вы не хотите перегружать пользователя слишком большим объемом информации. |
| Reference | Если у вас есть пользовательский интерфейс с большим количеством свойств, вы можете предоставить подробную информацию в справочном разделе. Использование таблиц — хороший способ обеспечить быстрый доступ к описаниям конкретных свойств. |
| Samples | Для пакетов, содержащих файлы примеров, вы можете включить подробную информацию о том, как пользователь может использовать эти файлы примеров в своих проектах и сценахA Сцена содержит окружение и меню вашей игры. Думайте о каждом уникальном файле сцены как об уникальном уровне. В каждой сцене вы размещаете свое окружение, препятствия и декорации, по сути проектируя и создавая свою игру по частям. Подробнее См. в Словарь. |
| Tutorials | Если вы хотите предоставить пошаговые руководства для сложных процедур, вы также можете добавить их сюда. Используйте пошаговые инструкции и включайте изображения, если они могут помочь пользователю понять. |
Формат документации
Markdown – это упрощенный формат, обычно используемый в пакетах. Многие службы размещения репозиториев (такие как GitHub и Bitbucket) поддерживают его для README и сайтов документации. Вы можете предоставить файл MD в папке Documentation~ в корневом каталоге вашего пакета, чтобы, если пользователь вашего пакета щелкнет ссылку View documentation на панели сведений Диспетчер пакетов Unity, пользовательская программа просмотра MD по умолчанию открывает файл.
Кроме того, вы можете использовать свой собственный веб-сайт для размещения документации. Чтобы указать расположение ссылки View documentation, чтобы она указывала на ваш собственный веб-сайт, задайте его с помощью свойства documentationUrl в вашем файле package.json.
Если вы решите использовать файл Markdown для документирования вашего пакета, вы можете найти дополнительную информацию о том, как писать файлы MD, на любом количестве справочных сайтов, например:
