Предыдущий урок: Developing Discourse Plugins - Part 6 - Add acceptance tests
Вы создали свой плагин, загрузили его в GitHub и добавили тесты. Отлично! Проблема в том, что о нём никто не знает.
Документирование вашего плагина
Для всех плагинов требуется качественная документация. Пользователи должны знать, что делает плагин, как его установить, какие важные настройки или изменения конфигурации необходимы и как им пользоваться. Документация к плагинам должна размещаться в двух местах: в файле README.md внутри вашего репозитория Git и в отдельной теме в категории Customization > Plugin.
Документация на GitHub
Файл README.md на GitHub важен, так как он отображается по умолчанию при посещении вашего репозитория. Как минимум, в README должно быть указано название плагина и краткое описание. Более полный README также будет содержать инструкции по установке, более подробное описание, базовые инструкции по использованию, лицензию и (при необходимости) скриншоты. Если дополнительные инструкции включены в тему плагина на Meta, обязательно добавьте ссылку на эту тему.
Пример минимально документированного плагина: Discourse Data Explorer
Примеры плагинов с более полной документацией: Discourse Solved, Discourse OAuth2 Basic и Discourse Ads.
Пример шаблона README для плагина
Обязательно обновите текст, заключённый в <>, в соответствии с особенностями вашего плагина.
## <Название плагина>
<Описание плагина>
## Установка
Следуйте [инструкции по установке плагинов](https://meta.discourse.org/t/install-a-plugin/19157).
## Как использовать
<Объясните, как включить плагин, необходимые шаги конфигурации и как им пользоваться>
## Скриншоты
<Включите скриншоты, если это необходимо для демонстрации использования плагина>
## Подробнее
<Включите ссылку на вашу тему на Meta, если там содержится более подробная информация>
## Лицензия
<Укажите лицензию вашего кода, большинство плагинов Discourse используют MIT>
Документация на Meta
Если документация на GitHub обычно краткая и «по делу», то документация на Meta — это место, где вы можете поделиться всеми подробностями о вашем плагине и убедить пользователей, почему они должны его использовать. Как минимум, ваша тема на Meta должна содержать краткое описание плагина и ссылку на репозиторий плагина на GitHub (чтобы пользователи могли его установить). Более полная документация также будет включать подробное описание с примерами использования, подробные инструкции по использованию, документацию по всем настройкам и параметрам конфигурации, а также скриншоты. Скриншоты играют ключевую роль, так как пользователи хотят видеть, что делает ваш плагин, а не просто читать об этом. Плагин, добавляющий провайдер аутентификации, вероятно, потребует только один скриншот, тогда как плагин, добавляющий новый интерфейс или вносящий серьёзные изменения, должен иметь их довольно много.
Документация на Meta обычно более персонализирована, чем на GitHub, у каждого автора плагина свой стиль документации. Какой бы стиль вы ни выбрали, убедитесь, что он понятен, легко читается и структурирован. Используйте заголовки по мере необходимости, добавляйте пояснения к скриншотам для объяснения сложных взаимодействий и старайтесь быть последовательными в форматировании. Избегайте искушения писать один огромный абзац.
Обновление документации
После написания первоначальной документации важно поддерживать её в актуальном состоянии.
Добавили новую функцию в плагин? Обязательно найдите время, чтобы задокументировать её.
Отвечали на один и тот же вопрос несколько раз? Подумайте о добавлении раздела FAQ в вашу тему на Meta.
Известная проблема, которую сложно исправить? Опишите её в вашей теме, чтобы пользователи знали, чего ожидать.
Поддержка вашего плагина
После публикации плагина и его документации администраторы сайтов, которые найдут его полезным, могут установить его на своём сайте и начать использовать. Это использование требует постоянной поддержки со стороны разработчика плагина. Вам нужно будет отвечать на вопросы администраторов сайтов, помогая им использовать ваш плагин. То, что было совершенно понятно вам, может быть непонятным для других, поэтому вам, возможно, придётся обновить код и/или документацию, чтобы прояснить это. Вы можете получать запросы на добавление новых функций, и вам придётся решать, добавлять их или нет.
Наконец, сам Discourse постоянно развивается. Хотя ваш плагин может работать безупречно сегодня, завтра что-то может измениться и сломать его. Обязательно следите за развитием Discourse, чтобы вы могли обновить свой плагин для поддержки последней версии Discourse, когда изменения затронут ваш плагин.
Другие части серии
Часть 1: Основы плагинов
Часть 2: Плагин-аутлеты
Часть 3: Настройки сайта
Часть 4: Настройка git
Часть 5: Интерфейсы администратора
Часть 6: Приёмочные тесты
Часть 7: Эта тема
Этот документ находится под контролем версий — предложить изменения можно на github.
