Documentation feedback gadget for wikis
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:
- Currently, it displays a feedback form at the bottom of an article in view mode in the “Help” namespace on Wikitech: https://wikitech.wikimedia.org/wiki/Help:Toolforge/How_to. Scroll down to the bottom of this page, to vote or see the Gadget in action (see screenshot below).
- 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:
- Copied the JS & CSS files in the MediaWiki namespace on Wikitech, with file names having a prefix “Gadget-”: https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.js, https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.css
- Defined the gadget in the MediaWiki:Gadgets-definition (includes modules used, dependencies, JS, and CSS file names, etc.), that would allow enabling it to all users on a wiki:
userfeedback[ResourceLoader|default|dependencies=ext.eventLogging]|userfeedback.js|userfeedback.css- Created the page MediaWiki:Gadget-Userfeedback which generated a label for the Gadget under Special:Preferences page and would allow users to enable or disable the gadget.
- Registered Schema:UserFeedback in the WikimediaEvents extension to make the event logging to work with the Gadget code on production wiki!
For now, we have to manually access the data with the help of steps highlighted here.
Relevant links
- Phabricator task: https://phabricator.wikimedia.org/T195119
- EventLogging Schema: https://meta.wikimedia.org/wiki/Schema:UserFeedback
- Gadget code on Wikitech: https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.css, https://wikitech.wikimedia.org/wiki/MediaWiki:Gadget-userfeedback.js
- Gadget in action, scroll down to the bottom of this page: https://wikitech.wikimedia.org/wiki/Help:Toolforge/My_first_NodeJS_OAuth_tool
If you’ve any questions about the implementation or need help or want to provide some suggestions ping me!
