Article feedback/Version 5/Technical Design

This page describes technical designs for the Article Feedback Tool Version 5 (AFT V5).

See also: feature requirements page, project overview page, useful links, as well as data and metrics plan.

Overview

The front end of the AFTv5 extension follows the ArticleFeedback extension: on article pages, a set of javascript modules attach a new div to the bottom of the page and fill it with a feedback form. On submission, the form is replaced by a CTA (call to action). Most of this code has been rewritten to allow for the selection of one of a set of possible forms, and one of a set of possible CTAs. Right now, form options 1, 2, and 3 are available, and the edit CTA is the primary choice (falling back to the learn more CTA if the current user cannot edit the article in question).

The back end is entirely new: rather than displaying aggregate data, the Special page shows a feed of the responses to the article passed in to the url. Right now the back end is not available in production; however, it is the first priority for the next phase. (For now, aggregate data from production is available via Dario's tools.)

Database schema

TODO: Rewrite for clarity

AFTv5 ERD

New schema here: Article feedback/Version 5/Technical Design Schema (will update and merge into this page soon)

When a feedback form is submitted, a record is created in the article_feedback table and also, depending on the feedback form, a number of rows may be added here, one row is inserted to article_feedback per recordable answer;

aaaa_feedback_id is the aa_id in aft_article_feedback, and aaaa_field_id is from the article_field table (which will eventually live in memcache, to save us some querying)

The value of aaf_data_type will determine which of the "aaaa_response_" columns is filled in - only one will be set for each answer row. Group ID is optional, and is used for grouping similar inputs on reports.

After that, there are four rollup tables that store reporting data and averages, which are updated on each for submission. There are two tables grouped by pageID, which count the sum of all revisions, back to the wgArticleFeedbackRatingLifetime, and two for revisions, which are grouped by revisionID. aft_article_revision_feedback_ratings_rollup is identical, save for including an "afr_revision" column, and the prefix changing from "aap_" to "afr_" These tables are used for aggregating numerical ratings (trustworthiness from 1-5, etc), and boolean inputs (did you find what you're looking for, with "yes" being a 4 and "no" being a 2, per WMF requirements). There are also a second set of rollup tables for counting the option-based questions. As above, there exists an aft_article_revision_feedback_select_rollup table, which is identical save for the revision_id column, and with the "aarfsr_" prefix. This is used for determining, for example, how many feedback comments were marked as suggestions versus problems or praises.

Free-text comment fields are not rolled up.

Overview of changes from AFTv4:

1. Prefix all table names with "aft_", per WMF.
2. Alter table article_feedback to drop columns aa_rating_id and aa_rating_value, and add columns for created and modified timestamps, is_submitted (boolean)
3. Create additional tables to store ratings and comments relationally, allowing for arbitrary fields in arbitrary "buckets" of feedback.
4. Rename article_fedback_pages and _revisions to something more descriptive of them being rollups, and add page/revision rollup tables to track averages of the boolen or select inputs (IE, the percentage who "did you find what you were looking for", or a breakdown on feedback type - "suggestion", "problem", "praise"). Add bucket column to all tables, for A/B split evaluation.
5. Change rollup logic to recalculate based on averages/sums, instead of adding/subtracting ratings totals on each submission.
6. Remove any restrictions on the number of feedback records a given user may record, or any capacity to overwrite/edit feedback records, per WMF 11/7, and allow any number of records to be recorded. Note that the actual ratings calculations are to be based on only the most recent feedback ratings per user per article revision, per Fabrice's 11/9 email.

NB: Extension installer files will have to be created or updated as needed.

Front End

After page load, the startup module (ext.articleFeedbackv5.startup.js) determines whether to display the form, and if so, loads the primary module (ext.articleFeedbackv5.startup.js). The primary module attaches a new div to the bottom of the page and invokes the jquery plugin (jquery.articleFeedbackv5.js) on it, then adds a link in a prominent location -- if the user scrolls to the bottom of the page, they'll see the form there; if they click the link, they'll see it in a overlay window. The particular form the user sees, and the exact location of the link, are chosen via bucketing.

If the user hits the submit button, it runs an error check and, if there are no issues, invokes an AJAX request. Upon successful return, the form is replaced with a CTA (call to action).

Flow

1. Startup phase (modules/ext.articleFeedbackv5/ext.articleFeedbackv5.startup.js)

   Determines whether to display the tool:

   • the user agent is supported
   • the page is an article
   • the category is whitelisted/blacklisted

   If all is well, it loads the main module.

2. Main phase (modules/ext.articleFeedbackv5/ext.articleFeedbackv5.js)

   Creates a new div, inserts it at the bottom of the article, and invokes the jquery plugin on it

   Selects a trigger link option and adds it to the page

   * NB: The click event calls the plugin's open-as-modal event

3. Init phase (modules/jquery.articleFeedbackv5/jquery.articleFeedbackv5.js, method $.articleFeedbackv5.init)

   Sets some state variables, chooses a display option, and binds the "appear" event to the holder div

4. Load phase (modules/jquery.articleFeedbackv5/jquery.articleFeedbackv5.js, method $.articleFeedbackv5.load)

   Sets up the bottom of the page and overlay containers, builds the selected form, and puts it in the appropriate container

5. Submit phase (modules/jquery.articleFeedbackv5/jquery.articleFeedbackv5.js, method $.articleFeedbackv5.submitForm)

   Runs validation, locks the form, and sends off an ajax request

6. Submit response phase (modules/jquery.articleFeedbackv5/jquery.articleFeedbackv5.js, method $.articleFeedbackv5.submitForm)

   On success, selects a CTA and loads it into the appropriate container, and removes the feedback link(s)

   On error, sets an error state and unlocks the form

7. CTA close

   If the user closes the CTA, it is entirely removed from the page and cannot be retrieved.

Query string options

You can choose a form and/or a trigger link option and avoid bucketing by passing the following in the url:

URL variable	Possible values	What it does
aftv5_link	A, B, C, D, E, or H	Show a particular trigger link
aftv5_form	0 or 1	Show a particular form

Form Bucketing Process

Bucketing mechanism flowchart

The decision of what form to display works like this:

1. If the plugin is in the debug state, and a form has been requested in the url, and that form is known, select it.
2. If there's a form-bucket cookie set, select it.
3. Otherwise, call mw.user.bucket.

The decision of what link to display works like this:

1. If the display bucket is 0 or 5, select - (nothing).
2. If the bucketing object is missing from the config, select -.
3. If the plugin is in the debug state, and a link has been requested in the url, and that link is known, select it.
4. Otherwise, call mw.user.bucket.

Note that the form selection doesn't check for a missing bucketing config object -- it should; this will be changed soon.

Submit AJAX call

This call is made when the user submits any of the feedback forms.

Call can be found at:
modules/jquery.articleFeedbackv5/jquery.articleFeedbackv5.js, method $.articleFeedbackv5.submitForm

Response can be found at:
api/ApiArticleFeedbackv5.php

Parameters:

Name	Type	Description
pageid	Integer	Page ID to submit feedback for
revid	Integer	Revision ID to submit feedback for
anontoken	String	Token for anonymous users
bucket	Integer	Which form was shown to the user
link	String	Which link, if any, the user clicked on to get to the widget (-, A through H, and TBX)
found	Boolean	Whether the user found what they were looking for (Form option 1)
comment	String	The text the user entered (Form options 1, 2, and 3)
tag	Integer	The type of comment entered, matching an id from aft_article_field_option (Form option 2)
rating	Integer	The helpfulness rating, on a scale of 1 to 5 (Form option 3)
trustworthy	Integer	The trustworthiness rating, on a scale of 1 to 5 (Form option 5)
objective	Integer	The objectivity rating, on a scale of 1 to 5 (Form option 5)
complete	Integer	The completeness rating, on a scale of 1 to 5 (Form option 5)
wellwritten	Integer	The well-written rating, on a scale of 1 to 5 (Form option 5)
expertise-general	Boolean	Whether the user self-identified as an expert (Form option 5)
expertise-studies	Boolean	Whether the user said their expertise came from academic work (Form option 5)
expertise-profession	Boolean	Whether the user said their expertise came from professional work (Form option 5)
expertise-hobby	Boolean	Whether the user said their expertise came from a hobby (Form option 5)
expertise-other	Boolean	Whether the user said their expertise came from something else (Form option 5)
email	String	The user's email address, if they want to be contacted (Form option 5)

Success response:
JSON object with one key, articlefeedbackv5, containing this object:

Key	Type	Description
result	String	Always "Success"
feedback_id	Integer	The id of the new row in aft_article_feedback
cta_id	Integer	The index of the selected CTA

Error response:
JSON object with one key, error, containing the token for the appropriate error message

Abuse Filtering

AFTv5 abuse filtering

AFT makes use of $wgSpamRegex, SpamBlacklist, and AbuseFilter. You can turn abuse filtering on by setting $wgArticleFeedbackv5AbuseFiltering to true. If any of these three are available they will be used to filter out abusive feedback. See flowchart for details.

AFT makes use of AbuseFilter's "disallow" and "warn" actions, and it provides custom actions to automatically flag incoming feedback:

Action	Source	Description	Message Key	Implemented
disallow	AbuseFilter	Prevents the posting of feedback	articlefeedbackv5-error-abuse	Yes
warn	AbuseFilter	Shows a message on your first attempt, but proceeds with other actions on your second attempt	Any key you set on the rule, but abusefilter-warning-feedback is available	Yes
aftv5flagabuse	AFTv5	Flags the incoming feedback as abuse	none	Yes, but commented out for 4/4 release
aftv5hide	AFTv5	Hides the incoming feedback	none	Yes, but commented out for 4/4 release
aftv5requestoversight	AFTv5	Requests oversight on the incoming feedback	none	Yes, but commented out for 4/4 release

You can edit the available warnings by changing the page "MediaWiki:Abusefilter-warning-{somename}" -- e.g., on prototype: http://prototype.wikimedia.org/release-en/MediaWiki:Abusefilter-warning-feedback

Special Page

TODO

1. Moderation tools - hide, promote (to talk page), or flag various pieces of feedback.
2. Sorting and filtering options - good comments first (how that's defined is unclear), newest first, etc. Basicallym tools are needed to manage or at least hide the inevitable flood of spam "feedback".
3. A special page, on the level of the talk pages - add a link to this in the not-quite-top-level navigation on said talk page.
4. Need to work out which bits of this page are must-have-now vs must-have-eventually.
5. Phase 1 will have a limited version with:
   1. Filters: All, Visible only
   2. Moderation Tools: Hide this comment
   3. Sorting: By date only
   4. Pagination: Fixed at 50

Platforms

We aim to support the following web browsers for phases 1.0 and 1.5:

• Internet Explorer 7+
• Firefox 3+
• Safari 5+
• Opera 10+
• Chrome 5+

NB: Support for IE7 was pulled from phase 1.0.

We will focus our testing on these top browser versions for Wikipedia:

• IE 8 (17%)
• Chrome 14 (16%)
• Firefox 7 (11%)
• IE 7 (7%)
• IE 9 (6%)
• Firefox 3 (5%)
• Firefox 6 (2%)

These will be tested on these desktop platforms:

• Windows (78%)
• Mac (8%)
• Linux (3%)

We are not currently planning to support IE6 or mobile platforms for phases 1.0 and 1.5, and will not show the forms at all on these unsupported platforms. In future versions, we will aim for 'graceful degradation' in unsupported platforms, and are working on a good definition for testing that objective.