Справочная информация
В этом посте я расскажу о процессе разработки гаджета обратной связи с документацией, который можно развернуть на любом сайте MediaWiki с небольшими настройками. В прошлом году я немало поработал над улучшением документации и руководств MediaWiki Action API с помощью студентов Информационных программ Викимедиа. В середине проекта я начал задаваться вопросом, были ли улучшения документации полезными и добавили ли какую-либо пользу потребителям наших API - и если да, то как мы могли бы это исследовать. Я начал с просмотра нескольких видеороликов с конференции Write the Docs - в частности, выступления Кэт Кинг: Создание документации для разработчиков на основе эмпатии о ее уроках, полученных при работе над документацией для разработчиков Twilio, поразили меня и дали некоторые идеи для следующих шагов !
Из выступления я выбрал одну из идей - инструмент обратной связи с пользователями, который мы могли бы интегрировать в вики. Мы представили это как форму обратной связи с кнопкой «палец вверх» и «палец вниз» для голосования. Хотя разработка или интеграция инструмента обратной связи кажется простой задачей для современных платформ, сделать это для вики - это не то же самое! Поэтому для чего-то столь же простого, как инструмент обратной связи с пользователями, нам требовалось сдержанное и экспериментальное решение, не требующее обслуживания и утомительной обработки анонимных данных.
Чтобы не изобретать велосипед, я изучил существующие решения в мире вики, которые мы могли бы использовать. Двумя из них, которые, казалось, стоит поразмыслить, были ArticleFeedback5 и VoteNy. Оба являются расширениями, которые можно интегрировать с MediaWiki для расширения его возможностей, которые по умолчанию имеют базовые функции. Расширение ArticleFeedback5 было разработано для англоязычной Википедии, но несколько лет назад было отключено по философским и техническим причинам, которые подробно описаны здесь. Несмотря на то, что VoteNy казался подходящим вариантом, ему потребовались корректировки дизайна и, следовательно, разработка нового расширения с повторным использованием некоторого существующего кода.
Поскольку разработка инструмента обратной связи проводилась исключительно в исследовательских целях; В идеале нам нужно было решение, которое можно было бы отключить от вики, как только оно будет служить своей цели. После небольшого обсуждения с более широкой командой мы решили разработать гаджет, который, по сути, в технической экосистеме Викимедиа, представляет собой javascript, который можно внедрить на стороне клиента в вики. Преимущество гаджета в том, что его можно быстро разработать, его код находится в вики, не обязательно требует проверки безопасности и может быть легко удален из вики. Что касается сбора данных, я планировал использовать EventLogging, который сделает его более плавным, а также предоставит возможность хранить данные только в течение 90 дней.
Подробная информация о реализации
Вот некоторые детали дизайна и реализации гаджета:
- В настоящее время он отображает форму обратной связи внизу статьи в режиме просмотра в пространстве имен Справка на Wikitech: https://wikitech.wikimedia.org/wiki/Help:Toolforge/How_to. Прокрутите страницу вниз, чтобы проголосовать или увидеть гаджет в действии (см. Снимок экрана ниже).
- Он использует базовую библиотеку MediaWiki, которая обеспечивает доступ к служебным программам через основные модули, поставляемые с программным обеспечением MediaWiki (например, значения конфигурации, настройки файлов cookie, события регистрации, вспомогательные функции и т. Д.). Подробнее о модулях.
- Для сбора показателей гаджет использует EventLogging. В это время он регистрирует данные; он ищет предоставленную Schema: UserFeedback в мета-вики и сохраняет информацию в поддерживаемом формате (включая идентификатор страницы, имя страницы и голосование) на сервере аналитики Викимедиа. Вот критический фрагмент кода, который делает все это возможным:
mw.eventLog.logEvent( ‘UserFeedback’, { page_id: articleId, page_name: pageName, vote: “Yes” } );
- Он полагается на модуль mw.cookie для обработки файлов cookie. Настройка файлов cookie гарантирует, что пользователю не разрешено повторно проголосовать за статью, если он сделал это уже в течение последних 10 минут.
- Это также включало тестирование с помощью инструмента отладки, eventlogging-devserver, чтобы гарантировать, что события регистрируются, а также гаджет в его полном состоянии на test.wikipedia.org перед перемещением его в производственную вики.
Этапы развертывания
Чтобы развернуть гаджет на Wikitech, необходимо выполнить следующие действия:
- Скопировал файлы JS и CSS в пространство имен MediaWiki на Wikitech с именами файлов, имеющими префикс Gadget-: https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.js, https: / /wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.css
- Определил гаджет в MediaWiki: Gadgets-definition (включает используемые модули, зависимости, имена файлов JS и CSS и т. Д.), Что позволит включить его для всех пользователей вики:
userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
- Создана страница MediaWiki: Gadget-Userfeedback, которая генерирует ярлык для гаджета на странице Special: Preferences и позволяет пользователям включать или отключать гаджет.
- Зарегистрированная схема: обратная связь с пользователем в расширении WikimediaEvents, чтобы журнал событий работал с кодом гаджета в рабочей вики!
На данный момент мы должны вручную получить доступ к данным с помощью шагов, выделенных здесь.
Соответствующие ссылки
- Задача фабрикатора: https://phabricator.wikimedia.org/T195119
- Схема регистрации событий: https://meta.wikimedia.org/wiki/Schema:UserFeedback
- Код гаджета на Wikitech: https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.css, https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.js
- Гаджет в действии, прокрутите страницу вниз до конца: https://wikitech.wikimedia.org/wiki/Help:Toolforge/My_first_NodeJS_OAuth_tool
Если у вас есть какие-либо вопросы о реализации, вам нужна помощь или вы хотите что-то предложить, напишите мне!