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 are alerts that are sent to you when important events take place that involve you or your activity on the site.

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.
 * take quick action, if you want to.

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

Note that no messages will be sent if the user checks the 'no email notifications' preference.

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
 * Subject
 * Body
 * Salutation
 * Event summary
 * Payload (e.g. comment, if any)
 * Call to action
 * Primary action link
 * Secondary action link(s) (as needed)
 * Signature
 * Footer
 * Subscription notice (*)
 * Preferences link(s) (*)
 * Legal notice, if needed (*)

(*) 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, sent 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".

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

Please improve this page to address these issues:

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

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 The email headers will include these fields:

The 'From' field will display the name of the site that is sending the notification, with an email address that includes the word 'notifications', as in this example:
 * From

'From: Wikipedia '

The 'Reply to' field will also display the name of the site that is sending the notification, with a different email address for tracking purposes, as in this example:
 * Reply to

'Reply to: Wikipedia '

The 'To' field will display the userID of the user that is receiving the notification, with the email address they specified in preferences, as in this example:
 * To

'To: Fabrice Florin (WMF) '

The 'Subject' field will feature a short phrase describing the event and including the site name, as in this example:
 * Subject

'Kaldari posted on your Wikipedia talk page'

Ideally, the subject would identify the actor, the action and the object of this event -- in addition to the site name, which is required for all subjects.

Body Contents The body of the email notification will include these fields:

The 'Salutation' field will display a short salutation that may include the userID of the recipient, as in this example:
 * Salutation

'Hello Fabrice Florin,'

Salutations may vary based on the type of notification. For example, the word 'Congratulations' may be used when the message is of a positive nature, but not if it is negative. Some messages may not include a salutation at all.

The 'Event summary' field will consist of a sentence or two describing what happened, who did it, where and when, as in this example:
 * Event summary

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

Event summaries may vary based on the type of notification. For example, the name of the page will be included when the object is an article, but not if it is a talk page. Some summaries will have more words than others -- and could even include a second phrase, if needed.

Each major group of notifications will share the same phrasing and phrase order, if possible (e.g. all instances of the 'page review' notifications would inherit the same sentence construction).

The 'Payload' field will display relevant information to help understand how or why the event took place, such as tag names for a page review or comments on a talk page, as in this example:
 * Payload

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

... or, in the case of a talk page post:

'Kaldari posted this on your talk page: "Hey Fabrice, nice work on the Breakfast article! I just linked it to the Nutrition article, and added more info on calories ..." '

The payload will not display more than a maximum number of characters (e.g.: 140 characters, the length of a tweet). If the payload exceeds that limit, the email notification will only display the first few characters up to that maximum, with three dots at the end, to indicate that it was truncated and there is more to it. Words should not be truncated, if possible.

Quoted comments should be displayed in a special font style (e.g. gray or italic), to distinguish them from the notification narrative.

The 'Call to action' field will include a short phrase inviting the user to take action, if they want, typically by clicking on the link below, as in this example:
 * Call to action

'Please improve this page to address these issues:'

Calls to action may vary based on the type of notification.

The 'Primary action link' field will be related to the call to action and shown on a line by itself, as in this example:
 * Primary action link

'Please improve this page to address these issues:

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

Primary links may vary based on the type of notification. Ideally, the selected link will help users find out what happened and take quick action, if they can and want to.

There should always be a primary link, if possible, to invite users to return to the site and participate more actively. That link should ideally not exceed 72 characters, if at all possible, so that line wrapping doesn't break the URL on some email clients.

The 'Secondary action links' field is optional and will be shown when one or more alternative action(s) can give the user other relevant options, as in this example:
 * Secondary action link)s)

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

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

Secondary action links may vary based on the type of notification -- and may not be needed at all, in some cases. This will be a trade-off between the need for alternative options and message simplicity.

Footer Contents The email footer will include these fields, which will be in smaller text font and generally stay constant across all notifications:

The optional 'Signature' field may display a final greeting and signature, including the site name, as in this example:
 * Signature

'Thank you!

The Wikipedia Team'

Signatures may vary based on the type of notification -- and may not be needed at all, in some cases.

The 'Subscription notice' field will display in small text the email address used for this subscription, along with instructions on how to unsubscribe, as in this example:
 * Subscription notice

'This email was sent to . If you don't want to receive these emails in the future, you can change your notification preferences here:'

The '* Preferences link(s)' field will enable the user to change their email notifications preferences, and be listed on a line by itself, as in this example:
 * Preferences link(s)

'http://en.wikipedia.org/wiki/Special:Preferences'

Another link may be required in the second release, to enable the user to immediately unsubscribe with a single click that doesn't require them to log in to change preferences manually.

There should always be at least one preferences link, which should ideally not exceed 72 characters, if at all possible, so that line wrapping doesn't break the URL on some email clients.

If needed, a short legal notice may be placed in small gray text at the end of the notifications. For example, many top sites such as Facebook, Google or LinkedIn all include a street address, perhaps for legal reasons. We are discussing this with Wikimedia's legal team at this time.
 * Legal notice

Digest Contents ... more specifications coming soon for daily and weekly digest 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