Mark as Helpful



'''This document is a work in progress. Comments are appreciated but this is not a final draft.'''

This document describes the behavior and mechanism for a way that users of Wikipedia may indicate that certain comments items are "helpful" and ensures that this gratitude is passed back to the originator.

This document describes a feature which is stand-alone but is written within the context of Feedback Dashboard.

This document is a work in progress. Feedback is welcome on the talk page.

Nomenclature
This document will refer to users who respond to comments via Feedback Dashboard as responders.

Individuals who leave comments (via MoodBar) are referred to as commenters.

Rationale
Currently, patrolling the Feedback Dashboard can be frustrating given that there is no "feedback loop." It is not always clear to responders that the commenters have even seen the responses, let alone found them helpful or engaging.

Hypotheses
It is hypothesized that providing a simple feedback loop will:
 * Improve overall morale of responders through expression of gratitude;
 * Improve the overall impression of commenters that they exist within a community;
 * Improve the overall quality of responses given due to harmonization (e.g., this answer was marked helpful 40 times)

Workflow
When a Commenter receives a response sent through the Feedback Dashboard, the response is added to the Commenter's talk page along with a parser hook reference that will cause a "Mark as helpful" control to appear.

If the user viewing the response has not previously marked the response as helpful, the control will invite the user to do so.

If the user viewing the response has previously marked the response as helpful, the control will indicate this state. It will also provide an "undo" feature (e.g., unmark the comment as helpful).

Along with this control, next to it, will be an indicator of the number of other users who have found the response helpful (if any). Additionally, there will be a way to expand and view the list of those who have found the response helpful. Since the list of people who found a response helpful could be extremely large, this will not be fetched until the time the "view" link is clicked.

Feedback Notification
It is necessary that the Responder be notified that their response was appreciated. However, at the time of this writing, MediaWiki does not support "simple" notification messages.

Ideally, when such a system exists, a simple "Username found your response helpful" notice would be added to the notification queue.

To avoid spamming the Responder's talk page, email notifications will be sent to the Responder.

Logging
While it is theoretically possible to log a "marking" as a contribution, at this point in time it is considered that logging these actions into a user's contributions list would be too spammy. They are intended to be lightweight.

Functional Requirements
Mark as Helpful indicators will likely need to be inserted into pages via parser hooks as they must pull data as well as be aware of the context in which they are being viewed (e.g., a user must be informed that they have already marked something as being helpful).

Since a feature like this could fragment the parser cache, it will have to be implemented in JavaScript. Upon page load, the "state" of any Helpful Indicator will need to be updated after the fact (in much the same way that other gadgets are done).

The parser hook will need to take the following arguments:


 * Response Object Type - This indicates the object type that is being responded to (e.g., "Feedback Dashboard Response" or "Welcome Template")
 * Response Identifier - This indicates the specific item in question (e.g., a revision ID, or template name). It may be required that there are
 * Count Display Mode - whether or not to display that "helpful count" in extended or abbreviated mode.

Data Model
Each entry requires the following elements to be captured:


 * Response Object Type - This indicates the object type that is being responded to (e.g., "Feedback Dashboard Response" or "Welcome Template")
 * Response Identifier - This indicates the specific item in question (e.g., a revision ID, or template name). It may be required that there are multiple columns to support this, as we do not have GUIDs.
 * User Name - The user name of the person who is clicking on the item (the person who found the object helpful). This can be an IP Address.
 * Responder User Name - the User name of the person who left the original response (the item being marked as helpful)
 * Edit Count - the Edit count of the user at the time of activation.
 * Language - The language of the project.
 * Project - The name of the project (Wikipedia, Wikinews, etc.)
 * Namespace - The namespace of the page (Main, User, User_talk, etc.)
 * Page Title - The title of the page where the user was when they indicated that the item was helpful.
 * Timestamp - A standard MediaWiki timestamp
 * Operating System - The user's operating system
 * Browser User Agent - The user agent of the browser.
 * Locale - The locale of the browser (not the language of the WMF project)

API Calls
- parameter: 1. mahaction - string: mark/unmark 2. type - string 3. item - int 4. page 5. system 6. locale 7. agent 8. token - return: json: result - success - error
 * action - markashelpful - mark or unmark an object identifier as helpful or unhelpful

- parameter: 1. type - string 2. item - int 3. prop - string metadata/formatted - return: json: result - success - data - error
 * action - getmarkashelpfulitem - list all the current helpful result for the object identifier

Future Thinking
This feature could be expanded such that it could be included in many other areas, such as help documentation or other explanatory text. This could help give us metrics as to the usefulness of such things, so that they could be written better going forward.

A further thought could be to add the feature to revisions (diffs), thus allowing editors to mark additions to the encyclopedia as being helpful.