Documentation feedback gadget for wikis

Srishti Sethi
May 13 · 4 min read

Background research

In this post, I highlight the process followed to develop a documentation feedback gadget, that can be deployed on any MediaWiki powered site with few tweaks. Last year, I worked quite a bit on improving the MediaWiki Action API docs and tutorials with help from Wikimedia outreach programs students. Halfway through the project, I started wondering if the documentation improvements were helpful and adding any value to the consumers of our APIs — and if yes, how could we investigate that. I began by watching a few videos from Write the Docs conference — particularly this talk from Kat King: Building Empathy-Driven Developer Documentation on her learnings from working on the Twilio’s developer documentation struck me and gave some ideas for the next steps!

From the talk, one of the ideas I picked was of a user feedback tool that we could integrate on a wiki. We imagined it to be a feedback form with thumbs up and thumbs down button for voting. Though, developing or integrating a feedback tool seems straightforward for modern platforms, doing it for a wiki was not the same! So for something as simple as a user feedback tool, we needed a low-key and an experimental solution that does not require maintenance and tedious handling of anonymous data.

To not reinvent the wheel, I looked into existing solutions in the wiki world that we could leverage. Two of them, which seemed worth reflecting were, ArticleFeedback5 and VoteNy. Both are extensions, that can be integrated with MediaWiki to enhance its capability, that by default comes with basic functionalities. The ArticleFeedback5 extension was developed for English Wikipedia but got disabled a few years ago due to both philosophical and technical reasons that are detailed here. Even though VoteNy seemed like a right match, it needed design tweaks and hence developing a new extension, while re-using some of the existing code.

As developing the feedback tool was purely for research purposes; ideally, we wanted a solution that could be unplugged from a wiki once it serves its goal. After a bit of discussion with a broader team, we decided to develop a gadget which essentially in the Wikimedia technical ecosystem is a javascript that can be injected from the client side on a wiki. The advantage of a gadget is that it can be developed quickly, its code lives on the wiki, does not necessarily require a security review and can be uninstalled from a wiki with much ease. For the data collection part, I planned to use EventLogging that makes it smoother and also provide an option to store data for 90 days only.

Implementation details

Here are some design & implementation details of the Gadget:

User feedback form
Confirmation message for a thumbs-up vote
Confirmation message for a thumbs-down vote
  • It uses the MediaWiki base library that provides access to utilities via the core modules that ship with MediaWiki software (e.g., configuration values, cookie setting, logging events, helper functions, etc.). See more on modules.
  • For gathering metrics, the Gadget uses EventLogging. At the time, it logs the data; it looks for the provided Schema:UserFeedback on meta-wiki, and stores the information in the supported format (including page id, page name, and vote) on the Wikimedia analytics server. Here is the critical snippet of code that makes this all possible:
mw.eventLog.logEvent( ‘UserFeedback’, { page_id: articleId, page_name: pageName, vote: “Yes” } );
  • It relies on a mw.cookie module for cookie handling. The cookie setting ensures that a user is not allowed to re-vote on an article if they have done so already in the last 10 minutes.
  • It also involved testing via a debugging tool, eventlogging-devserver to ensure that the events are getting logged and also of the Gadget as in its complete state on the test.wikipedia.org before moving it to a production wiki.

Deployment steps

To deploy the Gadget on Wikitech, here are a series of steps that were involved:

userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css

For now, we have to manually access the data with the help of steps highlighted here.

Relevant links

If you’ve any questions about the implementation or need help or want to provide some suggestions ping me!

Srishti Sethi

Written by

Technical Engagement @Wikimedia. More here: http://srishtisethi.com.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade