Notifications/Feature requirements

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

This page describes feature requirements for a new notifications system for Wikipedia, code-named Echo. Features below are for the first release of Echo, with a target date of January 2013. Features for follow-up releases may be added to this page at a later date.

Overview






Echo is designed to replace and augment existing notification systems on MediaWiki sites, as well as provide significantly more control to both users and developers as to how their notifications are handled, read, and deleted. This new notifications system seeks to unify the delivery of interaction messages in MediaWiki core, through a common API that can provide a uniform interface for users, as well as a scaleable, high-performance platform for developers. For a quick visual overview of this project, check the.

Problems & Solutions
We aim to solve these core problems:
 * There is no central notification system on Media Wiki sites
 * The current ad-hoc approach is inefficient
 * Users are not notified of key events
 * Users are confused by current notices

Echo will be developed to provide these solutions:
 * Provide a unified user experience
 * Help developers add it to their code
 * Promote editor engagement

User groups
For the first release, we will focus on these target groups of registered users:
 * new editor
 * active editor
 * very active editor/admin

However, we will focus on new editors (over experienced editors) for this first release, because new users need notifications more than power users.

Anonymous, unregistered users will not be targeted for this release.

Key features
Key features for Echo's first release include:
 * user menu
 * flyout
 * all-notifications page
 * preferences page
 * email notifications

For an overview of how these features work together, check the (see thumbnail to the right). In phase 1 of this project (Oct. 2012-Jan. 2013), we will create a simple version of these features, as described below. Other features under consideration for later development may be added in separate sections below.

Guidelines
Here are some general guidelines for providing the best experience for our users.

Every notification should be useful to our users. Quality is key to prevent users from turning off notifications.
 * Focus on quality

Notification should only feature the most relevant events, from the user's perspective -- highlighting just the key items from the watchlist, talkpage and other feeds.
 * Only important events

Notifications should be informative, like a good news story, and report objectively about who did what, when and where.
 * Newsworthy stories

Notifications should be concise, with the basic message under 10 words (up to 20 words if there are multiple user names, long article names or text snippets - which should be truncated after x characters)
 * Keep them short and sweet

Make notifications actionable, but don't overload the user with too many actions. Less is more.
 * Actionable

Don't send more than X notifications per day, if possible, so people don't view this as spam. (under discussion)
 * Daily limits?

Only send notifications to relatively active users. If a user stops visiting the site or clicking on the notifications, we should reduce the flow right away, so it is not perceived as spam. (under discussion)
 * Active users only?

Track how often users click on each type of notifications. If we find that clickthrough falls below a certain threshold (e.g. 15%) for certain types of notifications, we may want to consider removing them from the feed -- or not make them default options in preferences.
 * Measure the impact

These guidelines are still preliminary and subject to revision. Once we refine them some more, they may be useful when communicating with developers to use our Echo API to add notifications for their own extensions.

User Menu
The first visible touchpoint for users will be a 'notifications link' in the top menu that appears after the user's name in the upper right corner of any web page (referred to below as the 'user menu' or 'growler').

Currently this link is called "My notifications" on prototype. But we are exploring ideas which could lead to simply having a red badge without a label, as well as some notifications being added to other links, such as 'My talk' or 'My watchlist'.

If the user has "unread" notifications, the number of these unread notifications will appear next to the link as a 'badge' with a red background. This is likely be a red rectangle with a number ranging from 1 to 999, to match best practices. This badge will auto-update as outlined below, so that if a new notification comes in, the number will be changed as soon as practical.

Clicking on the "Notifications" link or on the red badge will display the Notifications Flyout (clicking on it again, or anywhere outside of the 'notifications flyout', will close that flyout, possibly marking all notifications as read).

Flyout
The flyout will feature a short list of new notifications, when the user clicks on the link or badge in the user menu.

Purpose The purpose of the flyout is to give users a quick view of the most recent notifications, to make them aware of new activity, with the option to click on them right away, ignore them, or review more notifications on the all-notifications page.

Number We currently plan to list up to 12 notifications in the flyout, but would only show about 6 notifications at a time, and the user would need to scroll to see the rest. If the user wants to see more, they can click on 'See all notifications' to go to the 'all-notifications' page. It is likely that these numbers will vary between devices, based on the height of your display -- and will be reduced for smaller screens, since scrolling in a flyout is not the best user experience. We will tweak these numbers once we have a first working version of the flyout we can test on various devices.

Order Notifications will be shown in reverse chronological order, with the latest notification shown first, based on its timestamp. The most recent notifications will remain on the flyout until replaced by newer notifications, which will push them down the stack incrementally, until they fall off from the flyout list. (The same ordering principle will be used in the all-notifications page, except that the list will be longer and separated by days: today, yesterday, all the way back to the past 7 days).

Scrollbar We will provide a scrollbar in the flyout for devices that can support them. This will be needed in order to see up to 12 items in the flyout, which will not all fit at once in the first view of the flyout, particularly if they all have payloads.

New vs. Unread 'New' means a notification that occurred recently (e.g.: minutes or hours ago), listed first in the flyout. 'New and unread' means a new notification you haven't clicked on yet. Its background could have a different highlight color, so you can tell it apart from the ones you have read. If you click on a notification, it becomes 'read' and loses its highlight.

Types The flyout would include a range of notifications, including these sample types now in development:
 * Edit reversions (e.g.: 'Vibha undid your edit to Breakfast')
 * Reviews ('Ryan reviewed a page you started: Breakfast.')
 * Mentions ('Fabrice mentioned you on this page: Dog')

We are now discussing the option of listing all talk page messages separately, though we have not finalized that decision yet (need to include Brandon in that discussion because it overlaps with Flow, our user-to-user messaging product).

Grammar The proposed grammar for each notification follows this format:

'[icon]  reviewed a page you started: . Tag(s): Copy edit ("Lots of spelling errors."). 1 hour ago'

This would be based on a common 'subject-verb-object' structure, with a few important attributes, as outlined in this pseudo code;

' []:  [""] '

Ideally, notifications would help answer these key questions about each event: who? what? where? when? why? how? -- if available in a concise format -- to give the user a better sense of what this event is about. Note that many events will not cover all these answers.

Examples Here are a few more examples of notifications:

Reviewed and marked for deletion: '[icon]  reviewed a page you started and marked it for deletion: . Deletion tag(s): Unambiguous copyright infringement ("cnn.com/plagiarized.htm"). 1 day ago'

Edit undone: '[icon]  your edit to : "This is already covered in the 'Nutrition' section." 1 minute ago'

See more examples under consideration on our Trello planning board.

Links Links available for each notification are still under discussion and may include:
 * separate links for the subject, action and object (as shown above)
 * a single link to the most important action (as Facebook does)
 * no link at all (unlikely, except when there is no link available)

Note that we may want to have a different implementation of these actions for the flyout and the all-notification pages. For example, we may only enable a single link for the flyout (over the entire notification), but offer separate links on the all-notifications page, as so:
 * The link for the actor-name  would go to their user page.
 * The link for the action-verb would go to the diff page showing how your revision was changed.
 * The link for the article-name <Breakfast would go to the article.

For now, we will stick to the current prototype's convention of separate links in the flyout (which matches general practices on Wikipedia). But we expect no more than 3 links per notification, at most. We will also aim to avoid using extra links with jargon words like 'diff', because they are hard to understand by new users (instead, we will simply link to the 'diff' if that is the best touchpoint.

All links from notices should open in the same window, not a new window.

Other links The flyout would include a link to the 'All Notifications' page, and possibly another link to the 'Notifications preferences' page. We are also considering (but have not settled on) a 'Clear New' button, which would let you clear the new notifications from your flyout.

Payload When important messages or event details are available in a concise format, we will aim to include short text snippets, to give the user a sense of what they might get if they click on it. But these snippets would be short, and truncated after 140? characters, with three punctuation marks ('...') to indicate there's more.

Timestamp The timestamp will be expressed as a 'time elapsed' indicator (e.g.: 1 min. ago, 2 hours ago, 3 days ago).

Bundling We will create a separate set of feature requirements for bundling and de-duping notifications, which may prove to be one of our main design challenges for this project. An example of bundling would be: 'Benny and 5 others edited a page you started.' Stay tuned for more on this topic.

Talk We discussed in our last meeting separating Talk messages from other notifications, if feasible and appropriate in the first release. One idea we considered for the first release is to show a red badge next to 'My talk', indicating the number of new talk messages, but taking you directly to your Talk page if you click on either 'My talk' or 'the red badge. Another option is to provide a separate flyout but were not sure how people would feel about having to click twice to go to their talk page until Flow is ready. However, a final decision on this issue would require Brandon's input, because it overlaps what he is working on with Flow.

Groups If we determine that users' mental models requires us to separate different types of notification in a single flyout, we may group them by category -- or offer tabs so you could filter the flyout list. If notifications are grouped by category, it is possible that some notifications listed at the top may contain be older than those contained in groups beneath it. For immediate development purposes, we will stay with the current model of stacking all notifications in a single list.

All notifications
... to be fleshed out in coming days ...

Preferences


The preferences page will feature a short list of options for email and web notifications, as part of the main user preferences.

Purpose The purpose of the preferences is to give users some control over which notifications to receive by email, how often to receive them and whether or not to display the web notifications flyout in the user menu.

Tab A special 'Notifications' tab will be displayed within the main user preferences page. Ideally, it would be listed in second or third position after the first tab you see when you open preferences. We may want to have a one-line explanation of what notifications are below the tab: "We send you notifications when users take actions on Wikipedia that involve you. You can change which notifications to receive below. Learn more >'. ('Learn more' will link to the help page or FAQ where we explain how notifications work.)

Links This notifications preferences tab will be linked from the 'All Notifications' page (and possibly from the 'Notifications' flyout, if space allows).

Sections The first version of preferences would consist of these sections:
 * Email Notifications
 * Email Frequency
 * Web Settings

Email Notifications This first section will enable users to choose which notifications to receive by email, using checkboxes.

Here are the proposed contents for that section:

'Email Notifications Notify me by email when someone:
 * reverts my edit
 * reviews a page I started
 * links to a page I started
 * features a page I started
 * posts on my talk page
 * mentions me'

For now, we are listing the first notification types now in development, but may add more options in the future. From a technical standpoint:
 * 'reverts and edit' includes edits undone and rolled back
 * 'reviews a page' includes all versions of reviewed, including reviewed + tagged, reviewed + marked for deletion
 * 'features a page' includes all versions of rated, featured or today's featured article

Email Frequency This second section will enable users to choose how often they want to receive notifications by email, using radio buttons.

Here are the proposed contents for that section:

'Email Frequency I would like to receive:
 * no emails about these events
 * individual notifications as they come in
 * a daily summary of most important notifications
 * a weekly summary of most important notifications

Notifications are being sent to myemail@mysite.com'

Web Settings This third section will enable users to choose whether or not they want to see the notifications web flyout and badge, using a check box.

Here are the proposed contents for that section:

'Web Settings
 * Show web notifications in my user menu'

By default, this option would be checked. But users who really don't want to see notifications on their browsers would have the option to turn off the flyout and the badge. They would, however, continue to have an 'All-notifications' page, even if it's not visible in their UI.

See All Notifications It would be helpful to include at the end of this preferences section a link to the all-notifications page: 'See All Notifications.'

Best Practices These feature requirements are inspired in part by best practices used by other top sites or platforms (e.g.: Facebook, Twitter, Google, LinkedIn, Quora), as shown in these slides, and summarized below:
 * most settings are about email notifications
 * 3 out of 5 sites provide a daily and/or weekly digest
 * average of 35 settings, 20 turned on by default
 * typically grouped by object type (e.g.: pages, messages)

Email notifications
Email notifications will alert you when important events take place on the site that involve you.

Purpose The purpose of email notifications is to inform you when something happens that relates to you, even when you are not on the site. These emails will enable you to do the following:
 * learn what just happened (who, what, where, when, why and/or how?).
 * go to the page where the event took place, so you can check it out for yourself.
 * invite you to take action, if appropriate.

Message Types Depending on your preferences, you can receive one of three types of email messages:
 * individual notifications
 * a daily digest
 * a weekly digest

Email Formats Email notifications will eventually be available in two different formats: For the first release, we will only support plain text emails, and add HTML format options in the second release.
 * plain text (first release)
 * HTML (second release)

Message Contents Most email messages will typically include these contents:
 * Header
 * From
 * Reply to
 * To
 * Date
 * Subject
 * Body
 * Salutation (*)
 * Event summary
 * Call to action
 * Primary action link
 * Secondary action link(s) (as needed)
 * Footer
 * Signature (*)
 * Legal notice (*)
 * Link(s) to change email preferences (*)

(*) The items asterisked above are likely to remain constant in most email messages.

Each of these content types are specified one at a time after the sample message below.

Note that in the case of email digests, multiple notifications may be bundled in a single message, which may require notification titles and dividers in between events.

Sample Message Here is an example of an individual email notification in plain text:

Subject: 'A page you started was just reviewed on Wikipedia: Breakfast'

Body:

'Congratulations, Fabrice!

Wikipedia editor Kaldari just reviewed a page you started, "Breakfast":

https://en.wikipedia.org/wiki/Breakfast

These tags were added to your page:
 * Copy edit ("Lots of spelling errors.")
 * No references
 * Stub

Please improve this page to address these issues.

If you have any questions, you can leave a message for Kaldari here:

http://en.wikipedia.org/wiki/User:Kaldari

Thank you!

The Wikipedia Team

This email was sent to . If you don't want to receive these emails in the future, you can change your notification preferences here: http://en.wikipedia.org/wiki/Special:Preferences'

Header Contents ... coming soon, along with other specifications for all message contents ...

Best Practices These feature requirements are inspired in part by best practices used by other top sites or platforms (e.g.: Facebook, Twitter, Google, LinkedIn, Quora), as shown in these slides, and summarized below:
 * most email notifications are HTML, requiring us to support this format as soon as possible
 * average of 3 links per email (min. 2, max. 7 in example slides
 * 3 out of 5 sites provide a daily and/or weekly digest)
 * more to come