Справочная информация

В этом посте я расскажу о процессе разработки гаджета обратной связи с документацией, который можно развернуть на любом сайте 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, необходимо выполнить следующие действия:

userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css
  • Создана страница MediaWiki: Gadget-Userfeedback, которая генерирует ярлык для гаджета на странице Special: Preferences и позволяет пользователям включать или отключать гаджет.
  • Зарегистрированная схема: обратная связь с пользователем в расширении WikimediaEvents, чтобы журнал событий работал с кодом гаджета в рабочей вики!

На данный момент мы должны вручную получить доступ к данным с помощью шагов, выделенных здесь.

Соответствующие ссылки

Если у вас есть какие-либо вопросы о реализации, вам нужна помощь или вы хотите что-то предложить, напишите мне!