Как написать полезную документацию для ассета в Unity Asset Store
Спроектируйте документацию Unity-ассета, которая помогает установить пакет, получить первый результат, разобраться в API и устранить частые проблемы.
Считайте документацию частью ассета
Покупатель не воспринимает документацию как отдельный бонус. Она является частью продукта и определяет, насколько быстро пакет получится установить, оценить и применить в реальном проекте. Инструмент с большим количеством функций, но неясной настройкой может выглядеть менее законченным, чем небольшой ассет с надежным путем к первому результату.
Пишите для человека, который знает Unity, но не знаком с внутренними допущениями вашей реализации. До начала настройки укажите поддерживаемые версии Unity, render pipeline, платформы, обязательные пакеты и существенные ограничения.
Постройте структуру вокруг пути покупателя
Начните с короткого обзора: что делает ассет, для кого он предназначен и какой результат дает. Затем добавьте требования, установку, быстрый старт, основные сценарии, настройку, примеры, программный интерфейс или API Reference, устранение неполадок и сведения о поддержке.
Обзор
Требования и совместимость
Установка и обновление
Быстрый старт
Основные сценарии
Настройки
Примеры
Scripting API
Устранение неполадок и FAQ
Поддержка и история версий
Не начинайте с полного перечня кнопок. Сначала помогите получить один полезный результат, а все настройки опишите на справочных страницах.
Сделайте быстрый старт с проверяемым результатом
В быстром старте должны быть указаны исходные условия и видимый итог. Назовите пример, сцену, GameObject, компонент или команду меню, которую нужно использовать. Уберите необязательную настройку из критического пути и покажите ожидаемый результат на скриншоте, если он устраняет неоднозначность.
Проверьте инструкцию в чистом проекте на самой ранней поддерживаемой версии Unity и в наиболее распространенной актуальной конфигурации ассета. Перечислите дополнительные пакеты до первого шага. Если действие изменяет настройки проекта или ресурсы, объясните последствия.
Свяжите сценарии, API Reference и устранение неполадок
Для редакторских инструментов и runtime-систем практические руководства и API Reference решают разные задачи. Руководство показывает совместное использование типов, а справочник точно описывает публичные классы, методы, свойства, параметры, возвращаемые значения и исключения. Ссылайтесь из сценария на нужную запись API, чтобы читателю не приходилось искать ее вручную.
Стройте раздел устранения неполадок на реальных состояниях: ошибки компиляции, отсутствующие зависимости, неподдерживаемый render pipeline, неправильные настройки импорта, потерянные ссылки и неожиданное поведение после обновления. Для каждой проблемы указывайте симптом, вероятную причину, решение и данные, необходимые службе поддержки.
Распространяйте и обновляйте документацию
На документацию можно сослаться из пакета, вложить ее в скачиваемый архив, приложить к выпуску и опубликовать на сайте продукта. Один HTML-файл удобен тем, что покупатель открывает его в браузере и не должен сохранять целой папку сгенерированного сайта.
Разместите версию ассета и дату обновления документации на заметном месте. С каждым выпуском проверяйте совместимость, установку, скриншоты, API и устранение неполадок. One File Docs объединяет обычные страницы руководства и C# API Reference в одном экспортируемом документе с поиском.