Notifications/Feature requirements

This page describes feature requirements for a notifications system for MediaWiki, code-named Echo. The features below are for the first release of Echo in early 2013.

Notifications inform you of new activity that affects you on Wikipedia -- and let you take quick action.

To learn more about Echo, check out this project hub, this testing page, the user experience page, the metrics plan and other related documents.

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 Echo slides.

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

Guidelines

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

Focus on quality

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

Only important events

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.

Newsworthy stories

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

Keep them short and sweet

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)

Actionable

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

Daily limits?

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

Active users only?

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)

Measure the impact

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. 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 groups

Workflow: Notifications for a new user's first steps on Wikipedia

For the first release, we will support three types of registered users:

new editor (our primary target)
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. Specifically, we will concentrate on some of the first notifications which a new user will receive after creating an account on Wikipedia, as shown in the workflow to the right.

This doesn't mean we will not support advanced editors, but we will initially emphasize notifications that help engage new users, who need this service most urgently.

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

Key features

User touchpoints for Echo

Key features for Echo's first release include:

user menu
flyout
all-notifications page
email notifications
preferences page

For an overview of how these features work together, check the user touchpoints map (see thumbnail to the right).

In phase 1 of this project (Oct. 2012-Jan. 2013), we will create a simple version of these features, focusing on a first desktop version for both web and email delivery, as described below.

Other features under consideration for later development may be added in separate sections below, including a mobile version, which will not be developed until the second release in spring 2013 (after WMF's mobile platform starts supporting log-in features).

User Menu

Echo notifications badge

The first visible touchpoint for users is a 'Notifications' badge 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').

Notifications badge: For the first release, we now plan to simply show a 'badge' (also called a 'growler') without a label next to the user name.

If the user has notifications they have not already seen, the badge will be red and will show the number of such 'unseen' notifications. 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 possible. To be clear, the number in the red badge refers to new, unseen notifications that occurred since the last time you looked at the flyout.

Notification flyout: Clicking on the "Notifications badge' will display the Notifications Flyout and zero out the badge, turning it gray. Clicking on it again (or anywhere outside of the notifications flyout), will close that flyout, and mark all notifications as read. The badge will then be grayed out, not red and will no longer have a number, until new unseen notifications are added. However, you may still click on that gray badge, which will display the flyout again, with its most recent notifications.

No notifications: The gray badge with the number zero would be shown next to the user name, even if there are no new notifications (or no notifications at all), so that the user can still click on it to easily access the flyout, the all-notifications archive or preferences. If the user has not received any notifications at all, the flyout and all-notifications pages would display this line of text where the notifications would have appeared: "You have no notifications at this time."

Echo notifications flyout

The flyout will feature a short list of new notifications, when the user clicks on the badge in the user menu. See mockup to the right.

Purpose: The purpose of the flyout is to:

make users aware of new activity that relates to them
give them a short list of the most recent notifications
enable them to take action on any event in that list
view more notifications on the all-notifications page

Number: We currently plan to list up to 10 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' 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 notifications shown first, based on their 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 10 items in the flyout, which will not all fit at once in the first view of the flyout, particularly if they all have payloads.
Highlights: When you first open the flyout, its 'new' notifications will be highlighted, so you can tell at a glance which are new. 'New' means a notification that you haven't seen yet, and that occurred recently, since the last time you opened flyout. To be clear, there should be as many highlighted notifications as the number in the red badge. If you click on a highlighted notification, it becomes 'read' and loses its highlight.

If needed, we may also want to provide a different, grayed-out highlight to indicate items that you have already clicked on previously. Its opacity could be reduced, making it light gray, so you can tell it apart from the ones you have not yet clicked on. However, this is a lower priority than the primary highlight for 'new' items described above.

Types: The flyout would include different thypes 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')

Sample notifications we are working on for the first release are listed below.

Grammar: The proposed grammar for each flyout notification follows this general format:

Fabrice Florin posted on your <talk page>.
"Thanks for your great work!"
1 hour ago   <View change>

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

<actor-name> <action> <object>:
["<payload-details>"]
<timestamp>   [secondary link, if needed - e.g.: <View change>]'

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.

Depending on the type of notification, we may use passive, rather than active voice. For example, we would use the active voice with the subject first for talk page messages or mentions that are related to person-to-person interactions. But for notifications where the object is more important than the actor, we may use passive voice, where the object is named first, then the actor, as shown in this example:

"<Breakfast>" was reviewed by Fabrice Florin.
Tags: Copy edit
1 hour ago

Examples: Here are a few more examples of notifications:

Reviewed and marked for deletion:

[icon] "<Breakfast>" was reviewed by Kaldari and marked for deletion.
Tags: Unambiguous copyright infringement
1 day ago

Edit undone:

[icon] Your edit to "Breakfast" was <reverted> by Kaldari. <View Changes>
"This is already covered in the 'Nutrition' section."
1 minute ago'

See more examples in the #Sample Notifications section below.

Links: Each notification will typically contain a single link to the most important action the user can take to respond to the event they are being notified about.

This primary action could link to any of these possible pages:

your talk page
an article page
a difference page
a discussion page

The primary action for each notification type is now described in this prioritized notifications list and will be posted in the #Sample Notifications section below.

For information clarity, we will bold the subject, action and object (as shown above), even if they do not have a link attached to them.

Note that the 'all-preferences' page will display more links than the flyout, to provide users with a wider range of actions.

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

Other links: The flyout would include a 'See all' link to the 'All Notifications' page.

If space allows, we may also provide one more link to the 'Notifications preferences' page.

We will not display any 'Clear New' button at this time.

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 an ellipsis ('…') 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). It may only appear when the user hovers over the notification, to reduce clutter.
No notifications message: If the user has not received any notifications at all, the flyout would display this line of text where the notifications would have appeared: "You have no notifications at this time."
Privacy: For the record, all personal Echo notifications will be completely private, both in the flyout and all-notifications pages, like all other websites. To clarify, even if a public notification is sent to the user in future releases (e.g. 'a new edition of the Signpost has been published'), the content of that notification will obviously be public (but the fact that you received that notification will remain private).

Message indicator

This new feature would display a prominent indicator whenever you get new messages, in addition to the red badge.

Purpose: The purpose of this message indicator is to:

make users aware of new messages posted on their talk page
provide a second visual cue in case users don't notice the red badge
enable users to view messages on their talk page

Background: Up until now, this function was served by the orange bar that used to notify users of new messages (affectionately called 'OBOD': the 'Orange Bar of Doom'). This orange bar was removed for logged-in users when the notifications tool was deployed on April 30, 2013. Many community members on the Notifications talk page think that message notifications are not prominent enough in the current tool, and are concerned that some users may not notice the red badge (which lights up next to your user name when you have new notifications). Because some messages are critical (e.g. warnings), a number of people have asked that we bring back the OBOD for registered users (note that the OBOD is already available to all logged-out or anonymous users). To address these concerns, we would like to deploy a more effective solution instead, to better serve the goals below.
Goals: We recommend that this new message indicator be:

prominent (easy to see)
clear (disambiguate messages from other notifications)
persistent (stays on until you click -- or easy to find)
consistent (with best UI practices)

Options: To identify the best design for this feature, we prepared a number of different options for this feature, which are described in more detail on this discussion page. In collaboration with community members who joined our IRC chat about these options, we identified a solution combining the best of options E and F -- using the orange background from E and the navbar integration from F, as shown below (see this full screenshot).

After testing that revised gadget, we reached consensus that this would be a reasonable solution to integrate in the Echo extension -- which we aim to do very soon. We encourage you to try out this new solution for yourself: go to Preferences > Gadgets and scroll down to the "Testing and development" section, then select 'Talk page alert prototype F2'. Be sure to clear your cache after you save your preferences. You may also need to post a message on your talk page from a separate account to test it.

Inline display: An inline display will appear when new messages are posted on your talk page, and feature a line of text with a link, such as:

'Talk: You have new messages'

This display will be shown in an orange box that will be part of the user navbar at the top of each page, next to the red badge -- and replacing the talk link. It will animate from right to left on page load, moving the user name to the left (these directions will be reversed in non-roman languages).

Click action: Clicking on the display will open the user's talk page, ideally scrolling to the first of unread messages, so they can read it quickly. This approaches matches current user expectations and is the simplest to implement. In cases where no section links exist, we may want to consider linking to the diff page instead.
Persistence: The display will show up on each page load, as long as there are unread messages. Messages are 'marked as read' when you visit your talk page, open the flyout or archive page with that message, or click the 'Mark all as read' button. See also this related bug for marking messages are read when you visit the talk page: bug 47912.
Preference: The display would be turned on by default. But it could be turned off in preferences, if a user objects to having this display in their user toolbar. Here is the proposed requirement for that preference.
Messages in flyout: At this time, we propose to continue listing message notifications in the flyout, to encourage users to start using the new tool. For future releases, we are considering displaying message notifications in a separate badge and flyout, as proposed in this Option H: Separate badges, to provide separate flyouts for notifications and messages. However, that option would require several weeks of development, and cannot be implemented right away. It will also require more research to validate that it would provide a better user experience.
Numbers: At a later date, we may want to provide the number of new messages in the visual display, but this feature could introduce complications and doesn't seem essential for the first release (it is not part of OBOD, for example).
Dismiss: At a later date, we may want to provide a way to dismiss the visual display, but this feature doesn't seem essential unless we are persistently obscuring critical content or functions, which is not advised in the first place.

This feature requirement will be fleshed out further once we get more community feedback and reach a decision of which option to implement.

All notifications

Echo all-notifications page

The 'All notifications' page (also called 'archive page') will feature a list of all recent notifications, when the user clicks on 'All notifications' in the flyout. See mockup to the right.

Purpose: The purpose of the 'All notifications' page is to give users a full list of all notifications received in the past week, in order to:

make them aware of recent events that relate to them
find previous events they might have missed or ignored
enable them to take a wider range of actions on any event in that list
show them how they can change their notification preferences

Sample All-Notifications Page Contents: Here is an example of what the 'all-notifications' archive page could include (rough draft):

Notifications (?)                (cog icon)

TODAY

[icon] <VBamba> posted on <your talk page>:
"Hey Fabrice, nice work on the Breakfast article!"
1 min. ago  <View change>

[icon] <Kaldari> mentioned you on <this page>.
1 hour ago  <View change>

YESTERDAY

[icon] <Breakfast> was reviewed by <Okeyes (WMF)>.
Tags: Unambiguous copyright infringement.
1 day ago

[icon] Your edit to <Breakfast> was reverted by <Kaldari>. <View Changes>
"This is already covered in the 'Nutrition' section."
1 day ago

APRIL 27

[icon] <Bsitu)> posted on your <talk page>.
"Hi Fabrice, I think you are making progress with the Breakfast article, but I think that you should
add a section on Nutrition." … <More>
2 days ago  <View change>

etc.

{  More  }

Header: The archive page header would have two icons on the same line as the 'Notifications':

a 'question mark' (?) icon next to the title (linking to the notifications portal)
a 'cog' icon on the far right (linking to notification preferences)

For a period of one month following launch, we would also display a small 'Feedback' text link next to the preferences cog icon, linking to the user survey. That text link would be removed when the survey ends.

This archive page header would look roughly like this:

Notifications (?)         Feedback | (cog icon)

Here are the links for this header:

question mark on en-wiki: https://en.wikipedia.org/wiki/Wikipedia:Notifications/FAQ

question mark on MediaWiki.org and other sites: http://www.mediawiki.org/wiki/Help:Extension:Echo

feedback link on all sites: https://www.surveymonkey.com/s/notifications1

cog icon link on en-wiki: https://en.wikipedia.org/wiki/Special:Preferences#mw-prefsection-echo

Linked pages would open in a separate tab or window, so the user doesn't lose their place.

Numbers: We currently plan to list up notifications for the past 365 days in the 'All notifications' page.

That number will vary from one user to another. For a new user, the total number of notifications may end up being only 10 notifications for that week, but for a more experienced user, it could include over 100 for that same week.

There is no need to include the total number of notifications on this page at this time.

By default, this page would only show about 25 notifications at a time, and the user would need to scroll to the bottom to see the rest (using infinite scrolling or 'More' button). (We will tweak this number once we have a first working version of the the 'All notifications' page that we can test on various devices.)

Order: Notifications will be shown in reverse chronological order, with the latest notifications shown first, based on their timestamp. The newest notifications will push back the older ones further down the list.
Sections: The 'All notifications' page will be separated into different sections, by days: Today, Yesterday, then actual dates ('Nov. 12'), all the way back to the past 7 days.
Length: Notifications will be relatively short in this 'All notifications' page, given that there could be more to list at once. So we will aim to keep them to 1 to 3 lines if possible, so it's easier to scroll down the list and see many of them at a glance.
Highlights: It doesn't seem necessary to show highlights to separate 'new' or 'unread' -- unlike on the flyout, where it seems more useful.
Icons: The 'All notifications' page would show small icons to identify the different types of notifications (e.g.: edit reversions, page reviews, talk page messages or mentions).
Grammar: The proposed grammar for each notification would be consistent with what we are using in the flyout and email copy, though slight variations in language may be needed for each format.
Links: While we are planning on offering a single link on the flyout, the 'All notifications' page will provide separate links for the subject and object (and sometimes action), to give more flexibility to the end user on that page (as Facebook and Google do already on their the 'All notifications' pages.)

Here are some examples of how these links might appear on the all-notifications page:

[icon] <Kaldari> posted on your <talk page>: "Thanks for your great work!"
1 hour ago   <View change>

[icon] <Breakfast> was reviewed by <Kaldari>.
Tags: Copy edit
1 hour ago

[icon] <Breakfast> was reviewed and marked for deletion by <Okeyes>.
Tags: Unambiguous copyright infringement.
1 day ago

[icon] Your edit to <Breakfast> was <reverted> by <Kaldari>. <View Changes>
"This is already covered in the 'Nutrition' section."
1 minute ago'

See more examples in the #Sample Notifications section below.

Here are examples of where these separate links might go to:

The link for an actor-name <Ryan> would go to their user page.
The link for an article-name <Breakfast> would go to that article.
The link for <View Changes> would go to the diff page showing how your revision was changed.
The link for <More> would go to the talk page (or other page) showing the full message.

See more examples in the #Sample Notifications section below.

All links from the all-notifications page should open in the same window, not a new window.

Payload: There are two primary types of payload for our first release:

text snippets (for talk page messages or reverted edits)
tags (for page reviews)

Text snippets: When important messages or event details are available in a concise format, we will aim to display short text snippets in the notifications on the 'All notifications' page, to give the user a sense of what they might get if they click on it. But these snippets will be short, and truncated after 255 characters, with a 'More' link to the page that the snippet is being excerpted from. These text snippets will typically be pulled from the 'edit summaries' (which can be handwritten, automatically generated, or a hybrid of the two), though in some cases it may be possible to pull the first line of the actual message (e.g. when a user adds a new section on a talk page). See more examples in the #Sample Notifications section below. These snippets should be displayed in between quotes, using a special font style (e.g. gray), to distinguish them from the notification narrative. They should typically be smaller than the main notification message, but not so small that they are hard to read by older users. Tags: In the case of notifications for page reviews, we will display the specific tags that were added to the page during the review. These tags will be comma-separated and kept short, so that we would only show the first 16? characters of a tag, followed by 3 dots (…) if they exceed that limit. In a later stage, we may provide a link to a flyout that would explain what these notifications mean, as proposed in the second mockup to the right. See specific examples in the #Sample Notifications section below.

Quick View of Tags

Tag Flyouts: In a later stage, we are considering showing a flyout on this page to explain what tags mean, when displayed in notifications, as illustrated in the mockup to the right. We plan to postpone this feature until we have a complete notifications system in place.
Timestamp: The timestamp would be expressed as a 'time elapsed' indicator (e.g.: 1 min. ago, 2 hours ago, 3 days ago).
Link to Preferences: We will provide on the All-notifications page a link to the Notification preferences, so that people can adjust their settings after seeing the list of their current notifications. This link will simply say 'Preferences'. At a later stage, we may want to consider providing a short summary of which preferences they have currently selected in the upper right corner of the page, so it's easier to understand why they are getting some of these notifications.
All-Notifications URL and Visibility: The URL for this All-Notifications page would be very short (e.g.: 'http://en.wikipedia.org/wiki/Special:Notifications'). This page will only visible to logged-in users, and they will only be able to see their own page, not anyone else's. (For debugging purposes, though, we may want to have a temporary way to inspect people's pages, to troubleshoot during development).
No notifications message: If the user has not received any notifications at all, the all-notifications pages would display this line of text where the notifications would have appeared: "You have no notifications at this time."
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:

many top sites go back up to a year in their all-notifications page (Facebook only shows 7 days)
most sites support up to hundreds of notifications on this page
notifications range from only 1 line (Facebook) to up to 9 lines (Google)
most sites include text snippets and time stamps for all notifications
most sites include either an icon or a photo for all notifications

Email notifications

Subject line of an individual Notification

Individual Notification UX

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' option in their preferences.

Email Formats: Email notifications will eventually be available in two different formats:

plain text (first release on MediaWiki)
HTML (next release on En-Wiki)

For the MediaWiki release, we will only support plain text emails, and add HTML format options in the En-Wiki release.

We will send both plain text and HTML to all users by default, and if their email client doesn't support HTML, it will show plain text instead. There is an email format switch in User Preferences.

Individual Email Notifications

Plain text email notifications

Sample Message - Single Notification

Here is an example of an individual email notification, sent in plain text:

From: Wikipedia <no-reply-notifications@wikipedia.org>

Reply to: No reply <no-reply-notifications@wikipedia.org>

To: Johnny Demo <jdemo@wikimedia.org>

Subject: Quiddity left you a message on Wikipedia

Quiddity left a message on your talk page, in this section: A kitten for you!

"Thanks for your work on the Breakfast article"

View message:
http://en.wikipedia.org/wiki/User_talk:Johnny_Demo#A_kitten_for_you.21

View change:
http://en.wikipedia.org/w/index.php?title=User_talk:Johnny_Demo&diff=prev&oldid=561106840

________________________________________________

To control which emails we send you, check your preferences:
http://www.mediawiki.org/wiki/Special:Preferences#mw-prefsection-echo
Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

Message Contents

Most email messages will typically include these contents, as illustrated in the sample above:

Header
- From
- Reply to
- To
- Subject

Body
- Event summary
- Payload (e.g. comment, if any)
- Call to action
- Action link

Footer
- Preferences notice (*)
- Preferences link (*)
- Company address (*)

(*) 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 by category in a single message, which may require dividers in between categories.

Header Contents

The email headers will include these fields:

From

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: Wikipedia <no-reply-notifications@wikipedia.org>

(this is the email that people see when they receive the emails, so they can filter it as needed)

Reply to

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: No reply <no-reply-notifications@wikipedia.org>

(this is the email that shows up if you try to reply, to make it clear you are not supposed to reply)

Note: We will accept replies, but delete them immediately, as currently implemented by operations and recommended by our legal counsel. So <no-reply-notifications@wikipedia.org> will be a working address, but we will simply route everything to /dev/null, for immediate deletion.

To

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: Fabrice Florin (WMF) <fflorin@wikimedia.org>

Subject contents

The 'Subject' field will feature a short phrase describing the event, as in this example:

Shiftchange left you a message on Wikipedia

The subject line can be considered as the most important part of an email message, because it is the first thing the user sees, and determines whether or not they want to open it. As a result, special attention will be given to this subject line, and we propose these guiding principles:

make it compelling
keep it short and sweet
identify the action which this message is about (e.g. review)
include the name of the user if it's an interactive notification (e.g. message, mention, thanks)
describe the object of this event (e.g. your page, though we're not including the full article names for now, as they could be too long)
include 'on Wikipedia' to make it clear where this happened to you (in case you miss the 'From' info)

Here are the subject lines which we are now considering for each notification category for the first release:

Smallbones left you a message on Wikipedia
Your page was reviewed on Wikipedia
Your page was linked on Wikipedia
Your edit was reverted on Wikipedia
Sun Creator mentioned you on Wikipedia
Kaldari thanked you on Wikipedia

Body Contents

The body of the email notification will include these fields:

Event summary

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

Wikipedia user Shiftchange posted on your talk page

or:

Wikipedia user Kaldari reviewed this page: "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).

Payload

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, as in this example:

Tags: Copy edit, No references, Stub

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

Wikipedia user 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.: 255 characters, as in the all-notifications page). 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 that there is more to it. Words should not be truncated, if possible. See the 'All-notifications' section above for more recommendations on payload contents.

See more examples in the #Sample Notifications section below.

Call to action and link

The 'Call to action' and 'action link' fields will will include a short call to action, as well as a separate link shown on a line by itself, as in this example:

View more:

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

Calls to action and 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 call to action and link, if possible, to invite users to return to the site and participate more actively. We may want to avoid links that exceed 72 characters, if at all possible, so that line wrapping doesn't break the URL on some email clients.

Footer Contents

The email footer will include these fields, which will generally stay constant across all notifications.

For the first release, the plain text version of this email footer could be separated from the body of the message by a divider. In future releases, when we implement an HTML version of the email notifications, this email footer could be shown in smaller gray text font, as most other top sites do.

Preferences notice and link

The 'Preferences notice' field will display in small text the email address used for this subscription, along with instructions on how to change their preferences. The 'link' field will enable the user to change their email notifications preferences, and be listed on a line by itself, as in this example:

________________________________________________

To control which emails we send you, check your preferences:

http://www.mediawiki.org/wiki/Special:Preferences#mw-prefsection-echo

Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

This link will take users directly to the preferences for email notifications and will require them to log in.

In future releases, we may consider updating this link 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 a preferences link, which should ideally not exceed 72 characters, so that line wrapping doesn't break the URL on some email clients.

Company address

This short legal notice with Wikimedia's corporate address will be added at the end of the notifications.

Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

The corporate address is required by law, and implemented by other top sites such as Facebook, Google or LinkedIn.

HTML single email notifications

This mockup shows a single notification in HTML email format.

We are planning to use HTML Email as the default format for all notifications, as soon as that feature is ready. HTML email notifications are now widely used on other top sites nowadays, as shown in these screenshots of best practices] -- and most major web destination typically use the HTML email format as a primary communication medium. One reason HTML emails are so widely used is because they present information more effectively than plain text emails, by using clear visual cues to inform users of new activity -- and invite them to take action more easily.

Please note that plain text emails will continue to be sent along with HTML emails, so if your email client cannot read HTML emails, you will see the plain text version instead, as described above. Also note that most email notifications are turned off by default for current Wikipedia users, so this may be a moot point for users who do not chose to enable them.

Here is an example of what copy would be included in an individual HTML email notification (see mockup to the right for the visual layout).

From: Wikipedia <no-reply-notifications@wikipedia.org>

Reply to: No reply <no-reply-notifications@wikipedia.org>

To: Kim Robin <krobin@gmail.com>

Subject: Shiftchange left you a message on Wikipedia

<Shiftchange> posted a message on <your talk page>:

"I am trying to expand on hydrocarbons and the environment topic so
that users may have more accurate information. Hydrocarbons is a
pretty critical educational topic too …"

View message [big blue button]

View changes [small link]

________________________________________________

To control which emails we send you, check your preferences.
Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

The proposed copy for subject lines and message body is detailed in this document, and is consistent with the attributes for each notification in this section.

For an example of a daily or weekly HTML email digest, check the appropriate section below. The proposed copy for subject lines and message body is detailed in this document, and is consistent with the attributes for each notification in this section.

For an example of a bundled HTML email digest, check the HTML email digest section below.

Email Digests

Daily/Weekly Digest

Email digests are bundled notifications that are sent daily or weekly.

Digest Goals: The goal of email digests is to group notifications into daily or weekly updates, so that:

users can get fewer emails sent to them, by getting regular updates instead.
users can get an activity summary of what is happening on the site, even if they don't have time to go there.
Wikipedia can stay in touch with users and engage them remotely, bringing them back to the site more often.
users can select which events to check and take immediate action on the most important ones (HTML only).

Email Frequency: The frequency of bundled email digests will be controlled by the user, in their preferences. This will enable them to select either 'daily' or 'weekly'. But the exact time and date will be determined by the Echo software.

Ideally, these digests would be sent at about the same time of day (or the same day of the week), if technically feasible, so that the user can expect to get them somewhat regularly. The actual time will be determined after consultation with engineering and operations teams. If at all possible, it would make sense to send the daily emails in the early mornings for the majority of our target users (e.g.: 3am PT for English Wikipedia). And it would also seem helpful to send the weekly digests on a Monday, at the start of the week. More research will be needed to finalize these proposed times and dates, so we can verify that these proposed assumptions are correct.

Contents: The contents of the email digest messages will be roughly the same as the all-notifications archive page. We will not attempt to exclude the notifications that have already been 'read' by the user, at least not for the first release. So it is possible that a user might see some notifications they have seen before, but we think this will be OK, since we are presenting these emails as 'summary of activity'.
Categories: We propose to group bundled notifications in categories, by notification type, as outlined in the Notification Categories section below.

The rationale for this approach is that it will allow us to show the most important types of notification first, for editor engagement purposes. For example, we would list talk page messages first, to encourage users to interact with others. We would also list positive notifications before negative ones (e.g. edit reverts would be last).

Threshold: We will only send up to 10 notifications at a time in a bundled email digest, to prevent the user from being overwhelmed. If the number of notifications exceeds that threshold, the most important notifications would be included in that short list, and the older notifications excluded, if possible. For example, in the case of a daily bundled notification, we would list all the notifications that occurred in the past 24 hours, then sort them by priority (see above order), then show the first 10 notifications from that sorted list, grouped by the categories above.
Plural vs. Singular: The subject line and email copy should be context-sensitive, and use plural or singular based on the contents of the message.

So that if there is only one notification, the message would say:

'You have a new notification' (instead of: 'You have new notifications')

(the same applies to category headers, which should say: 'Page link' instead of 'Page links' if there is only one notification for that category).

Plain text email digests

Sample Message - Daily Digest (Bundled Notification): Here is an example of a daily email digest, which is a bundled email notification (preliminary draft):

From: Wikipedia <no-reply-notifications@wikipedia.org>

Reply to: No reply <no-reply-notifications@wikipedia.org>

To: Fabrice Florin <fflorin@wikimedia.org>

Subject: You have new notifications today on Wikipedia

Hi Fabrice Florin,

You have new notifications today on Wikipedia. View them here:
http://en.wikipedia.org/wiki/Special:Notifications

________________________________________________

Talk page messages:

• Shiftchange posted on your talk page
• Accedie posted on your talk page
• Kaldari posted on your talk page

________________________________________________

Page reviews:

• "Breakfast" was reviewed by Kaldari
• "Dehli Metro" was reviewed by Accedie

________________________________________________

Edit reverts:

• Your edit to Nazi Germany was reverted by Kaldari

________________________________________________

To control which emails we send you, check your preferences:
http://en.wikipedia.org/wiki/Special:Preferences#mw-prefsection-echo
Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

HTML email digests

HTML Email Digest mockup - Centered header, left-aligned categories

HTML Email Digest mockup - Left-aligned header and categories

To provide a better user experience, we are developing HTML email digests that list today or this week's notification in a more visually appealing format, as shown in the mockups to the right.

We will send both plain text and HTML versions of these digests to all users in the same message, so if their email client doesn't support HTML, it will show plain text instead. There will not be any email format preferences unless we hear a strong user demand for this, to keep the UI as simple as possible. Example: Here is an example of a daily email digest's contents (working draft):

From: Wikipedia <noreply-notifications@wikipedia.org>

To: Fabrice Florin <fflorin@wikimedia.org>

Subject: You have new notifications today on Wikipedia

========= [Logo - centered] =========
     Hi Fabrice Florin,

Here's a summary of today's activity for you on Wikipedia.

[icon] Talk page messages

• <Shiftchange> posted on <your talk page>
• <Accedie> posted on <your talk page>
• <Kaldari> posted on <your talk page>

________________________________________________

[icon] Page reviews

• <Breakfast> was reviewed by <Kaldari>
• <Dehli Metro> was reviewed by <Accedie>

________________________________________________

[icon] Edit revert

• <Your edit> to Nazi Germany was reverted by <Kaldari>

________________________________________________

View them here

________________________________________________

To control which emails we send you, check your preferences.
Wikimedia Foundation, 149 New Montgomery St., 3rd Fl., San Francisco, CA 94105.

See this latest mockup for a preview of what this would look like in your email program. Future mockups may include:

examples with different logos for non-roman languages (e.g. globe) or non-wikipedia sites (e.g. MediaWiki.org)
include more examples of categories for first release
show examples of bundled notifications, consistent with the wording we are now using for bundling
consider removing the word 'notifications' in the category titles, to reduce visual clutter

The proposed copy for subject lines and message body is detailed in this document, which is consistent with the attributes for each notification in this section.

Other email specifications

Email Cadence: Email frequency can be adjusted to some extent in the user preferences, but is in fact more complex than that, if we want to avoid spamming users. For example, the initial notification about an event should be sent as close to real time as possible, but we may want to batch subsequent notifications if they exceed more than 3? emails in a given day. Sending all notifications immediately could lead the user being overwhelmed and unsubscribing. Sending all notifications batched into x hour bundles may be a reasonable low-effort compromise, but could mean missing an opportunity to drag users back to the site to do more work while things are still fresh. We will need to get the cadence right for a large percentage of users, or risk losing the privilege of communicating with them that way. For the first release, we will implement a simple frequency solution, but will want to tweak its cadence in the second release.
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

(for practical reasons, we will only implement plain text emails for the first release)

the subject line always includes a brief event description and the name of the site
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
most sites provide a quick way to unsubscribe

Preferences

Echo notifications preferences

The notifications preferences page features a short list of options for email and web notifications, as part of the main user preferences. It works in tandem with the 'dismiss' feature and 'default settings', as outlined below.

Purpose: The purpose of this preferences page is to give users some control over which notifications to receive by email or the web, how often to receive them and whether or not to display the web notifications badge 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.
Links: A link to notifications preferences will be included on both the 'Notifications' flyout and the 'All Notifications' page.
Sections: The first version of preferences would consist of these sections:

Email Notifications
Receive Notifications
Web Display

Email settings

This section will enable users to choose how often they want to receive email notifications and to what email address.

Here are the proposed contents for that section:

Email settings

Send me: [ individual notifications as they come in ]  (drop-down menu)

Send to: myemail@mysite.com | <Change your email address>

Email format:  [ HTML ]  (drop-down menu)

The first line would begin with the words 'Send me:', followed by a drop-down menu with these four options:

no email notifications
individual notifications as they come in
a daily summary of notifications
a weekly summary of notifications

By default, all users would get the first option ('individual notifications as they come in').

The second line would begin with the words 'Send to:', followed by the user's email address (if they already have one), and '<Change your email address>' (which would link to the 'email options' section of the 'user profile' preferences). If the user has not already provided an email address, the link would say '<Enter your email address>'.

The third line would begin with the words 'Email format:', followed by a drop-down menu indicating the format of email notification that will be sent to them, such as 'HTML', or 'plain text'. 'HTML' will be selected by default, but users would have the option to select 'plain text' instead.

Note: We recommend using the modern spelling of 'email' (instead of the older hyphenated 'e-mail' spelling), as it appears to be the standard spelling nowadays, according to Wikipedia or the Associated Press. This could be an opportunity to fix it everywhere else it appears in user preferences.

Notification Settings

This section will enable users to choose which notifications to receive by email or on the web, using checkboxes.

Here are the proposed contents for that section:

Notify me about these events:	Email	Web
• talk page messages (?)	*	√
• page reviews (?)	√	–
• page links (?)	–	–
• mentions (?)	√	√
• thanks (?)	√	–
• edit reverts (?)	√	–
• feedback (?)	√	–

To make it easier for users to understand what the notification categories mean, we propose to:

add a small question mark next to each notification category
show help tips in a 'tipsy' flyout when you hover over the question marks (with a sentence or two explaining what it means)
use short labels, favoring nouns with plurals, rather than verbs, and using (e.g. 'page links' instead of 'linked')

Here are the proposed help tips for each notification category:

talk page messages: "Notify me when someone posts a message or replies on my talk page."
page reviews: "Notify me when someone reviews a page I created, leaves a maintenance tag or nominates that page for deletion."
page links: "Notify me when someone links to a page I created from an article page."
mentions: "Notify me when someone links to my user page from any talk page."
thanks: "Notify me when someone thanks me for an edit I made."
edit reverts: "Notify me when someone reverts an edit I made, by using the undo or rollback tool."
feedback: "Notify me when someone marks article feedback as useful."

We also propose separate columns of checkboxes for web notifications (e.g.: in your flyout and archive page), because many users requested that option after testing the beta version of Echo. Note that for future releases, the same method could also be used to control which notifications are sent to your mobile phone (either as push or SMS), as Google now does in their own (notifications settings). For now, we are listing the notification categories for the first release, but may add more options in the future. From a technical standpoint:

'talk page messages' can only be turned off for email notifications, not for the web (because we believe they are too important to dismiss on the web)
'edit reverts' include edits undone and rolled back (but not edits manually reverted by another editor)
'page reviews' include all versions of reviewed, including reviewed + tagged, reviewed + marked for deletion
'feedback' include all versions of feedback marked as useful, including 'feedback for your watched pages' and 'your feedback'

Message Indicator Preference

This proposed preference would enable users to choose whether or not they want to see the Message indicator display next to the Talk link in their user menu, using a check box.

Here are the proposed contents for that preference:

New message indicator
[ ] Show talk page message indicator in my toolbar

By default, this option would be checked. But users who really don't want to see this message indicator on their browsers would have the option to turn it off. They would, however, continue to receive talk message notifications, even if the special indicator is not visible in their toolbar.

Defaults by User Group

To better serve the unique needs of different user groups, we propose separate default settings for new and current users. As a rule of thumb, a new user could benefit from more notifications than an experienced user, due to their lower level of activity and need for more guidance.

This could be accomplished by looking up the user's registration date and user group and specifying different settings based on these criteria.

Here are the defaults for each user group.

New users

Defined as users who register after Echo notifications are deployed

Enable individual email notifications
Enable web and email notifications for:
- talk page messages
- mentions
- page links
- page reviews
- thanks
- ~~system messages (e.g. welcome, get started, user rights)~~
Enable web notifications (but disable email notifications) for:
- flow
- education program
Disable web and email notifications for:
- edit reverts

Current users

Defined as users who registered earlier than 3 months ago or who have special user rights (e.g.: reviewer, rollbacker, steward, administrator, etc.)

Enable web and email notifications for:
- talk page messages
- ~~system messages (e.g. user rights)~~
No email notifications for talk page messages if the user has disabled talk page emails for the current tool in their preferences

('Email me when my user talk page is changed')

Enable web notifications (but disable email notifications) for:
- mentions
- page reviews
- edit reverts
- thanks
- flow
- education program
Disable web and email notifications for:
- page links
- welcome

One important requirement for current users is to synchronize their email notifications for talk page messages with their email settings for the existing talk page notification tool in their preferences (e.g.: if they have unchecked 'Email me when my user talk page is changed' at the bottom of the 'user profile' section). This will require us to run a special script in our first release on the English Wikipedia, to make sure that if a user disabled emails for the existing tool, they won't get emails from the new tool.

The above default settings are proposed here for the first release, and may be revised in future releases, based on user feedback.

Maintenance script details: To implement these default user settings from a practical standpoint, we plan to set the default options for Echo to the current user settings above. We would then use the AddNewAccount hook to set different preferences for new users, as they create new accounts. This would give us more flexibility in the future, and keep up from having to run expensive maintenance scripts every time we launch a notification. We will still need to run a small maintenance script to deal with the unique case of users who have 'Email me when my user talk page is changed' disabled, but this will only affect a small percentage of existing users and we already have the code for this written (in the old script).

Other Email Preferences

We may also want to have a section for selecting HTML vs. email later on, as well as reminding people of which email address their notifications are going to, with a link to the preferences that let you set your email address

Header Text: We may want to have a one-line explanation of what notifications are in the header text of the preferences page: "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' would link to the help page or FAQ where we explain how notifications work.)
See All-Notifications: It may be helpful to include at the end of this preferences section a link to the all-notifications page: 'See All Notifications.' This would make it easier for users to go back and forth between Preferences and All-notifications to see if they have the right settings.
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
average of 35 settings, 20 turned on by default
typically grouped by object type (e.g.: pages, messages)
3 out of 5 sites we studied provide a daily and/or weekly digest

Special Features

Here is a list of special features which have been implemented already. For a list of features under consideration, check this section.

Bundling

The 'Bundling' feature will enable users to only receive a single notification instead of many notifications about related events, to reduce information overload. Bundling aims to address one of the key challenges for this product: how to inform people without spamming them.

Purpose: The purpose of this feature is to:

reduce the number of notifications users receive for related events
show a single notification instead, bundling all related notifications into one
provide a single link where users can take meaningful action on all bundled notifications

Bundled Notifications: Only certain types of notifications can be bundled to meet the above objectives, in order to provide a single link where users can take action on all the bundled notifications. For our first release, only these two categories support bundling:

talk page messages (web-only)
page links (web + email bundling)

Here are examples of how these bundled notifications would be displayed in the flyout:

Tom Morris and 3 others posted on <your talk page>:
"Thanks for your good work on the 'Breakfast' article. …"

(instead of showing several different notifications about posts on your talk page)

or:

'San Francisco' was linked from 'California' and 2 others. <See all links to this page>.

(instead of showing several different notifications about links to your started page -- the bundled notification would point to the special page 'What links here')

A key requirement is that all notifications to be bundled share the same link, so that a user can easily take action on all these notifications from that same page. Developers of new notification types will have access to a special setting where they can enable or disable this bundling method. To prevent spam, this bundling setting will be turned on by default for new notification types, but clear guidelines will be provided to developers about the single link requirement. We may also want to include an automated check that a single link is shared by all bundled notifications, to prevent developers from inadvertently making it hard for users to take action.

We don't expect to bundle other notification types currently in development for the first release, because they are either unlikely to trigger multiple notifications, or can not provide a single link where the user can take meaningful action. That said, we are considering other types of notifications, which might benefit from bundling:

'5 editors contributed to <Porcelain money> since your last edit.' (See 'Activity for your recent edit')
'<Your watchlist> has 15 new events which may interest you.' (See 'Check out your watchlist')
'Your page on <Higgs Boson> is becoming popular (1k views, 20 comments and linked by 2 other pages today)'
'You have 6 new notifications on <Commons>' (the first cross-wiki notification we expect to implement)

Functional requirements: Different functional requirements will be needed for bundling web notifications in the flyout and all-notifications page, as well as for email notifications.

For web notifications in the flyout:

For each notification type that has web bundling enabled, look for all the recent events for which the user has not yet seen a notification
Sort all notification events by link, then group notifications that share the same link, and sort each group by date (removing any events which the user has already seen)
For each group, construct a bundled message that identifies the last user who triggered a notification, then gives the number of other contributors
The message will include only one action link for all bundled events on the flyout (e.g. a link to your talk page)
If a payload is required for that notification type, only show the most recent text snippet from the last bundled event
Show the bundled notification as soon as all messages are ready

For web notifications in the all-notifications page:

For each notification type that has web bundling enabled, follow the same basic requirements in the all-notifications page as for the flyout
Bundled messages will be constructed in the same format as for the flyout, but links to users and other pages will be added on all-notifications page

For email notifications:

For each notification type that has email bundling enabled, follow the same basic requirements as for web notifications for constructing messages, as outlined above
Send the first notification for each notification type and for each link group right away (if individual notifications are set in preferences)
If more events occur for that notification type and link group, delay sending a bundled notification for 4 hours (for individual notifications)
If even more events occur for that type and group after the first four hour period, send any bundled notifications every four hours (and reset the counter, as needed)
For the email digests, list the bundled notifications that took place that day or week for each type and link group, and send them at their regularly scheduled time

For example, here is what a user might receive over the course of a day (with preferences set to individual email notifications):

1pm: 'Tam Valley' was linked by Kaldari. [single event notification]
5pm: 'Tam Valley' was linked by Tom Morris and 2 others [bundled notification]
9pm: 'Tam Valley' was linked by BSitu [single notification]
1am: [no events took place, send nothing, start cycle again]
4am: 'Tam Valley' was linked by Fabrice Florin [single notification]
5am: 'Tam Valley' was linked Okeyes and 1 other [bundled notification]

Note that for maximum flexibility, we propose different settings for web and email bundling (for example, we will enable web bundling for talk page notifications, but disable email bundling to match current user expectations about this important notification type). Also, we propose that these bundled notifications do NOT show links under usernames in the all-notifications page: this greatly reduces the workload for developers, without affecting the user experience significantly.

Dependencies: Bundling features require a robust job queue infrastructure, which now does not exist for the current version of Echo.
Best Practices: Here are some examples of how this bundling feature is implemented on other sites like Facebook or Google:

JobQueue

Various asynchronous backend tasks performed by MediaWiki are added to one or more job queues and popped off those queues and processed. The current JobQueue class stores its data in MySQL tables and uses Memcached for performance and some features. The number of waiting jobs ebbs and flows through the day, but it is not uncommon to have hundreds of thousands waiting and for there to be a significant delay between queueing a job and it getting performed. Jobs will range from relatively cheap tasks like sending a password reset email to fairly expensive ones like transcoding media files.

Adding Echo notifications to the job queue massively increases the number of cheap to process jobs in the queue. It requires, at least for en-wiki, a new type of JobQueue class that can efficiently route notifications to users without load on the database, without waiting in line between longer running, less urgent tasks, and without delaying important tasks that impact many users

The new queue type is likely to be Redis based although this is not a requirement. It should provide a subset of the interface of the current JobQueueDB implementation that is sufficient for Echo's queue needs. Specifically it should provide:

* doBatchPush() that adds one or more jobs to the queue
* doPop() that takes a job off for processing.

Management methods like doAck(), doIsEmpty() and doGetSize() are desirable but not required.

Page update specific functionality like doDeduplicateRootJob() are not needed as that functionality will stay on the existing queue for the foreseeable future.

Mark all as read

The 'Mark all as read' button on the flyout lets you mark unread notifications as "read". This button only appears if you have more unread notifications than your flyout can display. Clicking on it will mark up to 100 recent notifications as "read". This will also zero out your badge in most cases. This is particularly useful for power users who get a lot of notifications and want a quick way to mark them as read without paging through their archive. (An easy way to test this feature is to reduce your browser window size, then use a separate account to send yourself a series of notifications. This should fill your flyout with more notifications than it can display, making this button appear.)

Blacklist

This feature would allow community members to prevent notifications from being triggered by users or pages which are deemed inappropriate for this service. Such users or pages would be designated by authorized users by adding them to one or more blacklists. A first version of this feature has been deployed for blacklisting users.

Purpose: The rationale behind the feature is that we need, in some situations, to avoid triggering notifications, because they would provide an unacceptable user experience, as described in use cases below.

The primary use case is users (this use case is now supported by the first version of this feature, see below). There are certain kinds of bot (SineBot, for example) which perform actions in relation to talkpages that do not constitute messaging. At the same time, other bots do leave messages, so a simple manipulation of the bot flag is not a valid mechanism to nullify notification triggers.

A second use case, which may be a different feature altogether, is that there are some pages that should not be the source of triggers for things such as user mentions. An example would be the sockpuppetry handling pages, or various planning/surprise awards pages.

A valid mechanism for handling these would be a per-wiki blacklist, similar to the existing spam blacklist, where users or pages can be listed; this is checked after an action, and if the action matches one of the blacklist entries, no notification is triggered.

Functions: For the first version of this feature, we now support these functions:

Users can now be blacklisted by the community if their notifications are deemed inappropriate
You can create a personal whitelist if you wish to get notifications from a blacklisted user

Check this related Bugzilla ticket 47946 for more background on this feature. To handle these cases, there exists a global blacklist initialized from the wiki LocalSettings.php and an on-wiki blacklist maintained by each project's community. The global user blacklist defaults to 'MediaWiki:Echo-blacklist' (see this enwiki global blacklist page) -- and the user whitelist defaults to 'User:Username/Echo-whitelist' (see this enwiki personal whitelist page). All on-wiki lists expect to receive one username per line with no special markup (and no underlines between words).

While a solution has been deployed for the first use case (user blacklists), we are still discussing the second use case (page blacklist), to determine its feasibility and relative importance. Blacklists/whitelists are not trivial to implement, so we'd like to make sure we only make it as complicated as needed and no more. For example, if SPI is the only page that will ever need to be blacklisted, we could get away with just using a config file blacklist (which is much simpler to implement).

After further discussions with developers and key stakeholders, we will update these feature requirements with more details.

Improved Notification Structure

Easytoread Notifications July

Notifications Content Structure-03

Notifications Content Structure-04-1

We propose to improve the notification language structure to give clearer information to users in the flyout, archive and emails. Our overall goal is to remove edit summaries with 'auto-comments' and other machine-generated content from the notifications payload -- and to feature instead clearly-labeled section names in the first sentence (when available), as well as text snippets from user messages in the payload (instead of edit summaries), where possible.

Purpose

The rationale behind the feature is that the current implementation of notifications language structure and payload is confusing to new and casual users.

Most talk page and interactive notifications now feature edit summaries in the notification payload -- which are hard to understand for a couple reasons:

many edit summaries are written as shorthand notes intended for other power users, and are often not very clear
some edit summaries include cryptic machine-generated 'auto-comments' which are confusing to new users
some edit summaries include a section name in between special characters (' */ '), which are also unclear

Notification payloads typically do not include the text snippet from the original post, which would better match user expectations.

And section names are not clearly called out as such, which would help users find more easily the source of the notifications.

Improvements

To address these issues, we propose the following improvements:

if we know the section name where the notification was triggered, show it as part of the notification's title (not in the payload)
only show the first 5 words of the section name, and truncate it if it's longer, adding three dots ('…') after the 5th word, FYI
if we can find a clear text snippet for the message that triggered the notification, feature that snippet in between quotes in the payload (instead of the edit summary)
if there is no clear text snippet for a talk page message, only an edit summary, do not show any payload
do not show any payload for mentions or thanks notifications, because the edit summary would be confusing
do not show edit summary for edit reverts either, because they are likely to be more confusing than helpful in their current state
do not send notifications for 'minor edits' -- because they are not likely to be important enough to justify the interruption

Here is an example of a notification you would get for a talk page message (once we have made these improvements):

Quiddity left a message on your talk page, in 'A kitten for you!'.

"Thanks for your work on the Breakfast article"

Here is an example of what this notification looks like now:

Quiddity left a message on your talk page:

/* A kitten for you! */ new WikiLove message

This current notification is confusing because the user doesn't know what the ' /* ' characters mean, nor what WikiLove means. They expect a more user-friendly message instead.

The improved version above includes these specific changes:

the section title has been moved to the first title sentence at the top.
a text snippet from the actual message is now quoted in the payload (instead of the unclear edit summary, which has been removed).
the section title has been removed from the payload.

Text snippet

The hardest part of this proposed improvement is how to determine if a text snippet is clear enough to be shown in the payload.

Here is our current proposal for when to show a text snippet in the payload, for discussion purposes.

Show a text snippet if:

the edit was made at the start of a new talkpage section (and was signed)
the edit was made at the end of a talkpage section, on a new line (and was signed)

In future releases, we will look for other ways to identify clear snippets, such as:

the edit was made in the middle of a section, but immediately after a blank line
the edit contains one or more punctuation marks (e.g.: a period at the end), suggesting that it may be a complete sentence
the edit contains a text string of at least 32? characters in a row (instead of isolated edits throughout the page)
the edit includes a user signature immediately following its text string

It is not clear yet if any of the ideas above are practical from a development standpoint, but they are offered here as examples of possible solutions for detecting appropriate text snippets. Final solutions will be determined in consultation with the developer of these proposed features.

For the first release, we will only support the first two use cases above (show a text snippet if the edit was made at the start -- or end -- of a talk page section).

Text snippets would be truncated after 128? characters, to avoid overloading the notifications with too much information. They would typically be followed by three dots in a row ('…') to indicate they have been truncated.

Notification Types

Core Notification Types

We expect that a wide range of notifications, will be developed over time for this project. Many of the ideas we've discussed are described in more detail below, as well as on this prioritized notifications list.

As a rule of thumb, we aim to develop notifications that are:

interactive: inviting new users to interact with more experienced contributors
positive: making new users feel good about participating on Wikipedia
frequent: likely to happen regularly, to keep users coming back

Notification Groups

Notifications can be divided into these four groups, to characterize their likely impact on users:

interactive
positive
neutral
negative

Here are some general definitions for each group:

Interactive is used for notifications that encourage users to interact with each other casually (e.g. talk page messages).
Positive is used for notifications that make users feel good about participating on Wikipedia (e.g. thanks for an edit you made).
Neutral is used for notifications whose effects on users cannot be anticipated, or which are not interactive, positive or neutral.
Negative is used for notifications that make users feel bad about participating on Wikipedia (e.g. reverting an edit you made).

Note that these general groups are different from the categories below, which are a bit more granular.

The sections below list notifications by group, when possible. Other sections include:

new user
power user
under consideration

Notification Categories

We are using categories to classify notifications of the same type for bundling purposes, as well as for preferences, as outlined below.

The rationale for this approach is that it will allow us to show the most important types of notification first, for editor engagement purposes. For example, we would list talk page messages first, to encourage users to interact with others. We would also list positive notifications before negative ones (e.g. edit reverts would be last).

Here are the main categories, listed in order of priority:

Talk page message
1. post on your talk page
Thanks
1. thanks for your edit
Mention
1. mention on another talkpage
Page link
1. link to a page you started
Page review
1. review of a page you started
2. review with maintenance tags
3. review with deletion tags
Edit revert
1. edit undone
2. edit rolled back
System messages
1. your user rights have changed
2. welcome
3. getting started (2)
(optional) Flow messages
1. flow-new-topic
2. flow-post-reply
3. flow-post-edited
4. flow-topic-renamed
5. flow-mention

Icons and types

Notification code-type	code source	notes
welcome (on Wikipedia)	Wikipedia Echo notification icon
welcome (elsewhere)	[1]	More subtypes (1 per wiki) requested in bugzilla:47662.
edit-user-talk	[2]
reverted	[3]
page-linked	[4]
mention	[5]
user-rights (on Wikipedia)	Wikipedia Echo notification icon
user-rights (elsewhere)	[6]
pagetriage-mark-as-reviewed	[7]	Needs to be split in 2 (PageCuration vs Patrol), per bugzilla:57517
edit-thank	[8]
gettingstarted-start-editing	[9]
gettingstarted-continue-editing	[10]
flow-new-topic	[11], [12]
flow-post-reply	[13], [14]
flow-post-edited	[15], [16]
flow-topic-renamed	[17], [18]
flow-mention	[19], [20]
default/fallback	[21]
featured	[22]	UNUSED
gratitude	[23]	UNUSED
pagetriage-add-maintenance-tag	[24]	UNUSED
pagetriage-add-deletion-tag	[25]	UNUSED
–		Return to Draft Namespace.Replaces Delete in most cases.(not in code yet)
course-talk-notification	[26]	Icon for Extension:Education Program course talk page edits

First Notifications

For the first release of Echo, we have developed this first set of notifications:

Talk page message ('you have a message')
Page review ('your page was reviewed')
Page link ('your page was linked')
Mention ('someone mentioned you')
Edit reverted ('your edit was reverted')
Welcome ('welcome to Wikipedia!')
Get started ('how you can contribute')
Thanks ('someone thanked you')
User rights ('your user rights have changed')

(All messages listed in https://git.wikimedia.org/tree/mediawiki%2Fextensions%2FEcho/HEAD/i18n English in en.json )

Interactive

This group includes notifications that invite new users to interact with other users on a regular basis (but that are not consistently positive or negative).

Talkpage Message

Sample notifications: talkpage messages

Workflow: Talkpage message

This notification occurs when someone posts on your talkpage. This includes events like starting a new section ('new message' or 'template'), or editing an existing section ('respond' or 'cleanup').

Smallbone posted on <your talk page>:
"Thanks for all your fine work on Wiki Loves Monuments!".

Here are some key attributes for this notification:

Trigger: User edit (click 'Edit' -- or 'New section')
Main Link: Talk page (to edited section, if possible)
Payload: Show 'Edit summary' (or 'New section first line')
Frequency: High
Priority: High
Category: Talk page message
Flyout Summary: [icon] Fabrice Florin posted on <your talk page>
Archive Summary: [icon] <VBamba> posted on <your talk page>
Email Subject: Shiftchange left you a message on Wikipedia
Email Summary: Wikipedia user Shiftchange posted on <your talk page>.
Web preference default: Enabled for all users (cannot be disabled on the web)
Email preference default: Enabled for both new and experienced users
Web bundling: Enabled
Email bundling: Disabled (we want to match current functionality on en-wiki, for a smooth transition)
Dismiss feature: Disabled (this notification type is too important to be dismissed)
Metrics group: Interactive
Metrics type: "edit-user-talk"

For interactive notifications such as this one, it seems helpful to include the user name in the email subject line 2 ('Shiftchange posted on your talk page'), instead of a generic subject line 1 ('You have a message on your talk page'). This may help new users recognize other members and form stronger relationships with them as a result. But we would only show a user name for registered users, not for anonymous users (IP addresses): in cases like this, we would use a generic message instead. If this is too complex for the first release, we may start with just the generic message.

For the first release, we're not required to specify different messages for each event type, and can simply use 'post on your talk page' as a general-purpose summary, as proposed above. For the new user we are now targeting, it does not seem necessary to have special messages such as 'started a new section on your talk page', which seem more complicated than newbies need -- and could be inaccurate.

Notes: For talk page messages supported by Echo, we plan to disable all the yellow talk page notices which now appear when your talk page has been edited. Disabling this current default new messages bar is basically a binary choice, not one dependent on notification type. Also, the yellow bars now tell you whether the talk page edit was one or multiple editors, which is not yet part of the Echo interface. If practical, we would not provide notifications for minor edits, unless they exceed 100 bytes per edit. Other than these caveats, we now expect that the proposed implementation for the first release would cover most of the needs of those who get the current yellow bar.

User Mention

This notification occurs when your username is mentioned by someone else, with a link on any talk page (other than yours):

Example: Sun Creator mentioned you on <this page>:

"I am impressed by the work that you have done on this project."

Attributes: Here are some key attributes for this notification:

Trigger: User edit including a link to your user page from any talk page other than yours, made by someone other than you
Main Link: Talk page where your name was added (go to the edited section that includes your name, if possible)
Payload: Show phrase that includes your name, if easy to do (or Edit summary as a backup)
Frequency: Medium
Priority: High
Category: Mention
Flyout Summary: [icon] Fabrice Florin mentioned you on <this page>
Archive Summary: [icon] <VBamba> mentioned you on <this page>
Email Subject: Sun Creator mentioned you on Wikipedia
Email Summary: Wikipedia user Shiftchange mentioned you on <this page>.
Web preference default: Enabled for all users
Email preference default: Enabled for new users, disabled for others
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled
Metrics group: Interactive
Metrics type: "user-mention"

Notes: See also: Manual:Echo#Technical details.

this feature only works if the mention of your name is linked to your user page (with double bracket links ([[ ]]), not single brackets - though it would be good if both worked)
this feature only works for posts inside a section of a talk page other than yours, or in the Project: namespace (e.g., 'Wikipedia:')
this feature only works if the post is signed -- by adding four tildes (~~~~) when the edit is posted, which are then converted into a signature
this feature only works if no lines are removed
Only 20 users can be mentioned at once. Any more than that, and the entire group is ignored as a probable mistake. (per phab:T52082)

Positive

We would like to provide more positive notifications for users in general, but particularly for new editors who have completed an unreverted edit, leading them towards a "happy path" towards further contributions.

Rationale: Oftentimes, new users receive no positive feedback from the community about their first edits, even if they are productive; they only get negative feedback if their edits are reverted. Many studies have shown that positive reinforcement plays an important role in increasing a user's productivity, and some have pointed out that it takes up to 5 positive notifications to make up for one negative one -- hence the important of such notifications. The assumption here is that some of these users are well-intentioned and could become constructive editors.

This problem can be illustrated by this visualization of new user's first edits. Our research suggests that about 74% of a new editor's first actions are article edits, and yet we currently offer no positive notifications to support these first article edits -- only a negative notification ('your edit was reverted').

Here are some of the first positive notifications we are developing to encourage new users on a regular basis.

Thank link on History page (mockup)

Thank you notification

This feature enables editors to send a 'Thank you' notification to users who make constructive edits, to give them positive feedback.

To make this possible, we now show a 'Thank' link on the article history page and diff page for each edit by a logged in user (next to 'Undo'). When you hover over that link, a tooltip says 'Send a thank you notification to this user.'. When an editor clicks on that link, the link changes to 'thanked'.

This would send this notification to the new editor:

<Kaldari> thanked you for <your edit> on 'Golden-crowned Sparrow':
'More info about the bird's song'

As seen in the notification flyout or email, the notification would include user name of the person who thanked you, a link to their user page, the name of the article you edited, a text snippet from your edit (or its summary), and a link to your edit's diff page. The link to the user page of the person who thanked you invites you to interact with that editor -- to ask a question or leave a message, for example.

This notification would link to the user page of the person who thanked you, as well as to your diff page for that edit ('View your edit'), where possible. In future releases, the diff page could include a message confirming who thanked you and linking to their user page (this requires more work than we have time for the first release). This confirmation could say something like: 'Kaldari (talk | contribs) thanked you for your edit.' (as shown in this mockup).

To keep things simple for this feature, we would not display the number of 'thanked' tags to anyone but the recipient of that notification. (Though over time, if the community finds this feature productive, we could expand it with a counter showing the number of positive responses, in future releases.) And we will not bundle multiple thank notifications, since the recipient wouldn't have any means of finding out who all thanked them if we did that.

This feature would be restricted to logged-in users only, because notifications do not work for anonymous users at this time. So the link would not appear next to anonymous edits (or edits from bots). If necessary, we could restrict this feature even more, and only show the link for new editors that have fewer than 100 edits, but do not recommend this, because other more experienced editors might find it valuable as well. If the link is hard to find, we could add a small icon next to the link, such as a heart, thumbs-up, or checkmark.

Here are some key attributes for this notification:

Trigger: Editor click on 'thank' link next to your edit on article history or diff page
Main Link: User page of person who thanked you (secondary link: diff page for your edit)
Payload: Show your edit summary
Frequency: High
Priority: High
Category: Gratitude
Flyout Summary: [icon] Kaldari thanked you for <your edit> on 'Golden-crowned Sparrow' … <See your edit>
Archive Summary: [icon] <Kaldari> thanked you for <your edit> on 'Golden-crowned Sparrow' … <See your edit>
Email Subject 2: Kaldari thanked you for your edit on Wikipedia
Email Summary: <Kaldari> thanked you for your edit on 'Golden-crowned Sparrow' … <View edit>
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Enabled
Dismiss feature: Enabled
Metrics group: Positive
Metrics type: "edit-thank"

From a technical standpoint, this feature would be pretty easy to implement in our time frame for the first release. The main question is whether or not our community would agree to this feature. But the outcome for new users is likely to be very constructive, from an editor engagement standpoint.

Notes: At this time, we are proposing that this feature be very simple, so we can develop it as part of Echo's first release. For that reason, we are proposing it to make it only persist in your all-notifications page, but not on any other page. As a result, no new data table is required to store these events, which makes the project more feasible in our time frame. But if this feature gains popularity and users want more capabilities, persistent data storage could be added later on, as needed.

This is implemented as a separate extension, which means that our communities would be able to enable or disable this feature on a per-wiki basis.

We are adding a throttling feature to prevent spam, so that you can only send up to 10 thanks notifications per minute, then get a message saying 'You have exceeded your limit. Try again later.'.

File Used

This notification occurs when a media file you uploaded or edited is used on a page:

Golden-crowned sparrow close-up was used by Smallbones on <Bird Migration>.

or, if the file was added to multiple pages since the last notification, bundle additional notifications as so:

Golden-crowned sparrow close-up was used on Bird Migration and 2 other pages. <See all pages that use this file>.

Example of a file notification

Here are some key attributes for this notification:

Trigger: User edit (on a page that now uses your file) > as reported by Global File Usage extension
Main Link: page that uses your file (if only one page)
Secondary Link: Commons file info page's File Usage section (ideally shown in Media Viewer, with meta-data panel open)
Payload: None
Frequency: Medium
Priority: High (positive)
Category: Media files
Flyout Summary: [icon] Golden-crowned sparrow close-up was used by Smallbones on <Bird Migration>.
All-notifications Summary: [icon] <Golden-crowned sparrow close-up> was used by <Smallbones> on <Bird Migration>.
Email Subject 1: Your file was used on Wikipedia
Email Summary: <Golden-crowned sparrow close-up> was used by <Smallbones> on <Bird Migration>. <View page>.
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Enabled
Email bundling: Enabled
Dismiss feature: Enabled (web-only)
Metrics group: Positive
Metrics type: "file-use"

Special requirements: This notification will only be shown/sent to users on Commons -- as cross-wiki notifications do not currently work. It would be ideal if it could be sent to all users who uploaded or edited a particular file (not just to the uploader, who may no longer be active).

New category: Note that we need to create a new category called 'Media files' in Notification settings, so that users can enable or disable these types of notifications.

New icons: We will also need to create a new icon for 'Media files' in Icons and types, so that file notifications can be distinguished from others (if necessary, we could re-use the 'cross-reference' link icon, but a cool 'media' icon would make these notifications stand out more.)

New metric type: We also will need to add a new Metrics type to our schema: "file-use" -- as well as update notification dashboards for Commons, so we can track the usage of this notification.

For more info about this notification, see this Mingle ticket. The multimedia team plans to develop this notification in spring 2014.

More positive notifications

These positive notifications are listed in separate groups below, because they are for power users, and/or aren't targetted for the first release:

WikiLove
Huggle Notifications
Started Page - WikiProject
Started Page - Rated
Started Page - Featured
Started Page - Feedback
Featured Feedback

Neutral

This group includes notifications that are not particularly interactive, and not consistently positive or negative.

Started Page - Marked as reviewed

Workflow: Page reviewed

This notification occurs when a page you started is marked as reviewed (and possibly tagged in the process):

Porcelain money was reviewed by <Sriharsh1234>.

Here are some key attributes for this notification:

Trigger: Editor review (or patrol) of page you started
Main Link: Your page
Payload: Tags (if any)
Frequency: Low
Priority: Medium
Category: Page review
Flyout Summary: [icon] <Porcelain money> was reviewed by Bsitu.
Archive Summary: [icon] <Tamalpais Valley> was reviewed by <HFung>
Email Subject: A page you started was reviewed on Wikipedia
Email Summary: <Tamalpais Valley> was reviewed by Wikipedia user <Jorm>
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Neutral
Metrics type: "pagetriage-mark-as-reviewed"

For notifications that are about a page, such as this one, it would seem helpful to include the page name and the user name in the email subject line 2 ('Life of Pi (film) was reviewed by TheHelpfulOne'). However, this could be an issue for long article titles, which may need to be truncated after 20? characters, so the subject line can be understood. If this is too complex for the first release, we could start with just the generic subject line 1 ('A page you started was reviewed on Wikipedia').

If needed, we could use the same summaries above for all notifications related to 'started page reviews' below. For the first release, it doesn't seem essential to change the wording for each subgroup, if we think the tags tell clearly what the issue is. See sections below for more details.

Notes

this notification is triggered by the PageTriage extension, which asks Echo to send the notification to the end user
these two related notifications are also recognized by Echo, depending on what button is pressed on PageTriage's Curation Toolbar:
- Started Page - Tagged
- Started Page - Marked for deletion
there are 5 or more possible variations of this type of notification, which are described in more detail on this prioritized notifications list.

Started Page - Tagged

This notification occurs when a page you started is marked as reviewed and also tagged in the process:

<Transcarpathian Art Institute> was reviewed by QatarStarsLeague.
Tags: Orphan, No categories, Copy edit

Here are some key attributes for this notification:

Trigger: Editor review (or patrol) of page you started -- with tags
Main Link: Your page (with templates)
Payload: Tags
Frequency: Low
Priority: Medium
Category: Page review
Flyout Summary: [icon] <Transcarpathian Art Institute> was tagged by QatarStarsLeague. Tags: …
Archive Summary: [icon] <Transcarpathian Art Institute> was reviewed and tagged by <QatarStarsLeague>. Tags: …
Email Subject 1: A page you started was reviewed on Wikipedia
Email Summary: <Transcarpathian Art Institute> was reviewed and tagged by <QatarStarsLeague>. Tags: …
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Neutral
Metrics type: "pagetriage-add-maintenance-tag"

If needed, we could use the generic email subject 1 above for the first release, to reduce complexity and deploy sooner.

Note: there are 72 possible tags that may need to be supported for this notification type.

Started Page - Linked

This notification occurs when a page you started is linked from another page:

Portland Public Library was linked by Peteforsyth. <See all links to this page>.

or, if multiple links were made to this page since the first one, bundle additional notifications as so:

Portland Public Library was linked by Peteforsyth and 2 others. <See all links to this page>.

Here are some key attributes for this notification:

Trigger: User edit (linking to page you started)
Main Link: 'What links here' page (see example)
Payload: None
Frequency: Medium
Priority: High (positive)
Category: Cross-reference
Flyout Summary: [icon] Portland Public Library was linked from <Portland, Oregon>.
All-notifications Summary: [icon] <Tamalpais Valley> was linked from <Rancho Saucelito>. <See all links to this page>.
Email Subject 1: Your page was linked on Wikipedia
Email Summary: <Portland Public Library> was linked from <Portland, Oregon>. <View page>.
Web preference default: Enabled for new users, disabled for others
Email preference default: Enabled for new users, disabled for others
Web bundling: Enabled
Email bundling: Enabled
Dismiss feature: Enabled (web-only)
Metrics group: Neutral
Metrics type: "page-link"

If needed, we could use the generic email subject 1 above for the first release, to reduce complexity and deploy sooner. For notifications that are about a page, such as this one, it would seem helpful to include the page name and the user name in the email subject line 2. However, this could be an issue for long article titles, which may need to be truncated after 20? characters, so the subject line can be understood. But if this is too complex for the first release, we could start with just the generic subject line 1.

Special requirements: This notification will only be shown/sent for article namespace links, and only for internal links in double brackets. We will not show or send it for talkpage links, transcluded links, redirects or page moves -- or any other page links that could create spam. This notification would be opt-in for existing users, which means that it would only be shown/sent to current users if the check it in their preferences. However, it would be checked by default for new users (see defaults section of the preferences page). Also note that any page with a prefix (e.g. 'Wikipedia:' or 'Help:') is excluded, so no page link notifications will be sent for these types of pages.

Negative

This group includes notifications that can make new users feel bad about participating on Wikipedia. In general, we recommend that these notifications only be shown if the user 'opts-in' in their preferences.

Started Page - Marked for deletion

This notification occurs when a page you started is marked as reviewed and also nominated for deletion, including one or more deletion tags (AFD / CSD / PROD):

<Government of Kazakhstan Airline> was reviewed and marked for deletion by Jetstreamer.
"This article may not be suitable for inclusion in Wikipedia, according
to Wikipedia's policies and guidelines."

Here are some key attributes for this notification:

Trigger: Editor review (or patrol) of page you started -- with deletion tags
Main Link: Your page (with templates)
Payload: Tags
Frequency: Low
Priority: Medium (negative, but important)
Category: Page review
Flyout Summary: [icon] <Government of Kazakhstan Airline> was marked for deletion by Tchay. Tags: …
Archive Summary: [icon] <Transcarpathian Art Institute> was reviewed and marked for deletion by <Jorm>. Tags: …
Email Subject 1: A page you started was reviewed
Email Summary: <Angry Birds> was marked for deletion by Wikipedia user <QatarStarsLeague>. Tags: …
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Negative
Metrics type: "pagetriage-add-deletion-tag"

Note: there are about a dozen possible tags that may need to be supported for this notification type.

Edit reverted

Sample notifications: edit reverts and reviews

Workflow: Edit reverted

This notification occurs when your edit was just reverted (undone or rolled back):

Your edit on 'Hurricane Sandy' was <reverted> by <Knowledgekid87>.

Your edit on 'Hurricane Sandy' was reverted by <NewsAndEventsGuy>.
"Undid revision 521530151: With what other sentence in the lead is it redundant?"

Here are some key attributes for this notification:

Trigger: Editor reversion (click 'Undo', 'Rollback', manual or automated)
Main Link: Diff page (shows difference between your edit and theirs)
Payload: Show 'Edit summary'
Frequency: High
Priority: Low (negative, opt-in)
Category: Edit revert
Flyout Summary: [icon] <Your edit> on 'Government of Kazakhstan Airline' was reverted by Knowledgekid87.
Archive Summary: [icon] <Your edit> on <Transcarpathian Art Institute> was reverted by <Eloquence>.
Email Subject 1: Your edit was reverted on Wikipedia
Email Summary: <Your edit> on <Angry Birds> was reverted by Wikipedia user <NewsAndEventsGuy>.
Web preference default: Disabled for new users, enabled for others
Email preference default: Disabled for new users, enabled for others
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Negative
Metrics type: "reverted"

New user notifications

This group includes notifications that only impact new users -- and are targeted for the first release, even though they only occur once or infrequently.

Welcome

This web-only notification occurs when a user creates a new account, to make them feel at home. This notification was originally developed by the E2 team, and the copy change below was recommended by the E3 team.

Example: Welcome to Wikipedia, FooUser! We're glad you're here.

Attributes: Here are some key attributes for this notification:

Trigger: Account creation (and email validation, if email address is provided)
Main Link: None
Payload: None
Frequency: One-time, web-only
Priority: Very High (positive)
Category: System Message
Flyout Summary: [icon] Welcome to {{SITENAME}}, $1! We're glad you're here.
Archive Summary: [icon] Welcome to {{SITENAME}}, $1! We're glad you're here.
Email Subject: no email for this notification
Email Summary: no email for this notification
Web preference default: Enabled for all users (cannot be disabled)
Email preference default: Disabled for all users (cannot be enabled)
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Disabled (system messages like these are required)
Metrics group: Positive
Metrics type: "welcome"

Note:

This is a web-only notification, which will not be sent via email
The follow-up 'Getting Started' notifications (see below) should be generated within 24 hours, after they validate their email and either make an edit or not.

Getting started

In addition to the generic welcome message above, E3 and E2 are collaborating on follow-up 'getting started' notifications aimed at new users, with the goal of providing them with a way to get started with editing. Since the core ux hypothesis of Echo is that notifications can and should drive activity on the site (rather than be a destination in and of themselves), we are testing this theory with messages that dovetail with our work onboarding new Wikipedians in Extension:GettingStarted, which will contain the following two notifications.

Attributes

Trigger: Email validation (will also not fire if registration is more than 30 days ago)
Main Link: Special:GettingStarted
Payload: None
Frequency: One-time
Priority: High (positive)
Category: System Message

Web preference default: Enabled for all users (cannot be disabled, one time only)
Email preference default: Enabled for new users who provide an email address, disabled for others
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Disabled (system messages like these are required)
Metrics group: Neutral
Metrics type: "welcome"

Getting Started (no article edits)

For users who have no article (NS0) edits yet.

Flyout text: Wikipedia is a free encyclopedia written by people like you. Get started by making your first edit!
Email subject: Get started with editing Wikipedia
Email text: Wikipedia is a free encyclopedia written by people like you. Get started by making your first edit!

Wikipedia is a free encyclopedia written by people like you. Get started by making your first edit!

Visit http://en.wikipedia.org/wiki/Special:GettingStarted for a list of easy ways to improve pages.

Getting Started (1+ article edits)

For users who have one or more article (NS0) edits.

Flyout text: Nice work! You've already made your first edits to Wikipedia. If you're looking for more to do, here are some easy ways to help
Email subject: Easy ways to improve Wikipedia
Email text: Nice work! You've already made your first edits to Wikipedia. If you're looking for more to do, there's a list of easy ways to help at URL.

Nice work! You've already made your first edits to Wikipedia.

If you're looking for more to do, there's a list of easy ways to help at http://en.wikipedia.org/wiki/Special:GettingStarted

Power user notifications

Though we are targetting new users for the first release, we would like to provide some notifications that would be valuable to experienced editors in the first release.

Rationale: the existing feature set for Echo's first release is now targeted mainly at the new user. This is intentional, since experienced users already know where to get information and don't need notifications as much as new users. But we would like to include in the first release at least one advanced feature that fills a need for the experienced editor.

Criteria: We plan to select one or two low-risk power-user notifications for the first release, as long as they can match the following criteria:

are viewed as really useful by the editor community
are feasible, with a low effort in engineering that will not delay the schedule
can be used by many power users over a period of time, so we get more bang for the buck
are simple enough that we can manage subsequent feature requests that will inevitably come from experienced editors

Based on conversations with advanced users, we have identified these notifications that generally address these criteria:

User rights notifications ('your user rights have changed - you now have rollbacker privileges')
Blocked user post ('someone you blocked has left a message on their talk page' -- currently requires administrators to watchlist the talk pages of people they've blocked)
Rated page ('your page was rated')
Featured page ('your page was featured')
WikiProject ('your page was added to a wikiproject')

While these last three notifications seem attractive, they may not be easy to adapt for other projects than the English Wikipedia - requiring an external API to provide the most flexibility for each project. For that reason, we may want to wait until such an API is available in future releases.

You can see some of the notification ideas we discussed at the end of this Google spreadsheet (in the yellow section).

User rights

This power user notification occurs when your user rights have changed (e.g.: 'you now have rollbacker rights') -- whether you are being granted a new right, or whether someone removes a user right you used to have.

Examples

Your user rights were changed by Bsitu. You are now a member of this group: 'rollbacker'. <Learn more>

or

Your user rights were changed by Bsitu. You are no longer a member of this group: 'rollbacker'. <Learn more>

Attributes: Here are some key attributes for this notification:

Trigger: User rights change (typically by another user, such as administrator, bureaucrat or other authorized user)
Main Link: User group rights page (wikis can override it to provide a different link that explains policy for each user right, as listed below)
Payload: None
Frequency: Infrequent (only once for each new user right granted)
Priority: High (mostly positive)
Category: System Message
Flyout Summary: [icon] Your user rights were changed by Bsitu. You are now a member of this group: 'rollbacker'. <Learn more>
Archive Summary: [icon] Your user rights were changed by <Bsitu>. You are now a member of this group: 'rollbacker'. <Learn more>
Email Subject: Your user rights have changed on Wikipedia
Email Summary: Your user rights were changed by <Bsitu>. You are now a member of this group: 'rollbacker'. <Learn more>
Web preference default: Enabled for all users (cannot be disabled)
Email preference default: Enabled for new users who provide an email address, disabled for others
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Disabled (system messages like these are required)
Metrics group: Neutral
Metrics type: "user-rights"

Notes

By default, this notification would be sent each time you receive (or lose) one of these user rights (links below are provided for the English Wikipedia):
- blocked user (see special message below)
- rollbacker
- reviewer
- autopatrolled
- File mover
- Account creator
- IP block exemption
- Edit filter manager
- administrator
- bureaucrat
- oversighter
- Checkuser
- Steward

Notes

The default 'Learn more' link where users can learn more about their new rights would be this User group rights page. This page appears to be automatically generated for every wiki project. But each wiki project could replace it with another page that is easier to understand, such as this User access levels page for the English Wikipedia.

Each wiki project can customize user right names, messages and links for their site, and override the default configuration locally, using localized MediaWiki messages ('l10n' instead of 'i18n' -- see Internationalization and localization). For example, the English Wikipedia may want to provide a different link for each user right, as listed above. Whichever technical solution is used, it should make it easy for an authorized administrator to change these settings without having to change the Echo extension itself, with these fields: user right name | message for that user right (including link).

Users who give themselves user rights will not get a notification.

In the next release, we may want to factor in global changes of local rights, as recommended by Oliver Keyes.

A separate notification would be used for 'autoconfirmed' (or 'confirmed') users, with a special message that's more meaningful to a new editor.

A separate notification would be used for 'blocked' (or 'unblocked') users, with a special message that's more meaningful for that purpose

Blocked user post

This power user notification occurs when someone you blocked (as an administrator) has left a message on their talk page. (This currently requires administrators to watchlist the talk pages of people they've blocked).

Someone you blocked has left a message on their <talk page>.

Trigger: Blocked user edit
Main Link: Blocked user talk page
Payload: Edit summary or first sentence
Frequency: Low

Started Page - Rated

Sample notifications: recognitions and cross-references

This notification occurs when a page you started receives a Good article rating:

<Angry Birds> was rated as "Good" by HFung.

Here are some key attributes for this notification:

Trigger: Editor adds category to page you started
Main Link: Your page
Payload: None (unless there's an edit summary?)
Frequency: Low
Priority: Very High (positive)
Category: Recognition
Flyout Summary: [icon] <Angry Birds> was rated as "Good" by HFung
Archive Summary: [icon] <Angry Birds> was rated as <"Good"> by <HFung>
Email Subject: Your page was rated on Wikipedia
Email Summary: <Angry Birds> was rated as "Good" by Wikipedia user <HFung>
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Positive
Metrics type: "page-rated"

Started Page - Featured

This notification occurs when a page you started is linked from another page:

<Thomas Percy> was featured by Kaldari

Here are some key attributes for this notification:

Trigger: Editor adds category to page you started
Main Link: Your page (or category page?)
Payload: None
Frequency: Low
Priority: Very High (positive)
Category: Recognition
Flyout Summary: [icon] <Thomas Percy> was featured by Kaldari
Archive Summary: [icon] <Thomas Percy> was featured by <Kaldari>
Email Subject: Your page was featured on Wikipedia
Email Summary: <Thomas Percy> was featured by Wikipedia user <Kaldari>.
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled (web-only)
Metrics group: Positive
Metrics type: "page-featured"

Started Page - WikiProject

This notification occurs when a page you started is added to a Wiki Project:

'Muir Woods' has been added to the <California WikiProject>.

Trigger: User edit (to WikiProject page?)
Main Link: WikiProject page (to edited section, if possible)
Payload: Show 'Edit summary' ?
Frequency: Low
Priority: High (positive)
Category: Cross-reference

Under consideration

This group includes notifications that show potential for engaging users, but that require more research to determine their feasibility.

They generally aim to add value for new and experienced editors in these areas:

providing positive feedback to new users
making the watchlist more visible to new users
providing notifications to power users
other infrequent notifications

We aim to investigate these features in coming weeks, and determine which of these can be realistically implemented for the first release, then flesh out their requirements further.

How to use your watchlist

This proposed feature would send a one-time notification after a user's first edit, to let them know they can track it in the watchlist.

This would offer the following benefits:

make the user aware that they have a watchlist
provide a link to the watchlist, so they can check it out
explain that they can use the star button to add items to their watchlist

It is intended to work with the Watchlist guided tour and the Add edited pages to new user watchlist features. This notification would link to the guided tour on the watchlist page and would require that the watchlist have at least one entry from the user's first edits.

It is scheduled for the first release of Echo, and the WMF's Editor Experimentation team (E3) has expressed interest in collaborating with us to develop the guided tour for this notification as part of their onboarding project.

In the flyout, this notification might look like this:

'Did you know you have a watchlist? <Learn how it works>.'

Here are some key attributes for this notification:

Trigger: after your first edit
Main Link: watchlist page (with a guided tour)
Payload: None
Frequency: One-time
Priority: High (useful to new users)
Category: System Message
Flyout Summary: [icon] Did you know you have a watchlist? <Learn more>.
All-notifications Summary: [icon] Did you know you have a watchlist? <Learn more>.
Email Subject: Did you know you have a watchlist on Wikipedia?
Email Summary: Did you know you have a watchlist? <Learn how it works>. [could add a bit more copy if needed]
Web preference default: None for system messages
Email preference default: None for system messages
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Disabled
Metrics group: System
Metrics type: "watchlist-how-to"

Note: This notification will only be sent once. This feature depends on the next two features below to provide a complete user experience: 'Watchlist Guided Tour' and 'Add pages to new user watchlists'.

WikiLove

This notification occurs when someone posts WikiLove on your talkpage:

Utar sent you <WikiLove>:
"Good call! Thanks for making that revision."

Here are some key attributes for this notification:

Trigger: User WikiLove post
Main Link: Talk page (to edited section)
Payload: Show first line of message
Frequency: Medium
Priority: Very High
Category: Gratitude
Flyout Summary: [icon] Fabrice Florin sent you <WikiLove>
Archive Summary: [icon] <VBamba>sent you <WikiLove>
Email Subject: VBamba sent you WikiLove on Wikipedia
Email Summary: Wikipedia user <VBamba>sent you <WikiLove>.
Web preference default: Enabled for all users
Email preference default: Enabled for all users
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled
Metrics group: Positive
Metrics type: "wiki-love"

If needed, we could use the generic email subject 1 above for the first release, to reduce complexity and deploy sooner. Notes:

Although this notification is clearly positive, it is already provided through the Talk page message notification, so we are postponing it for now.
When we have more time, it would make sense to split this WikiLove notification from the Talkpage message, so it can have its own heart icon and wording.

Autoconfirmed notification

This notification would be sent when you become autoconfirmed. On the English Wikipedia, most user accounts that are more than four days old and have made at least 10 edits are considered autoconfirmed, as described in this User access level page.

Examples

Your user rights were changed. You have been 'autoconfirmed' as an editor and can now move pages, as well as edit semi-protected pages. <Learn more>

Attributes: Here are some key attributes for this notification:

Trigger: Administrator action
Main Link: this User access level page (wikis can override it to provide a different link that explains policy for each user right, as listed below)
Payload: None in most cases (but we may want to include the block rationale for blocked user right changes, as noted below)
Frequency: One-time
Priority: High (mostly positive)
Category: System Message

Notes:

This notification proposal is not planned for the first release of Echo and could be developed in collaboration with the E3 team, as part of their onboarding project.
No user name is required for the person who granted the 'auto-confirmed' right (since it is automatically done by the system). But a user name could be shown for a manually 'confirmed' notification.

Blocked user notification

This notification would be sent when you become blocked, indefinitely blocked -- or unblocked. On the English Wikipedia, editors can be blocked indefinitely by administrators, which restricts their ability to edit on any page other than their own talk page.

Examples

Your user rights were changed. You have been 'indefinitely blocked' and can no longer edit on Wikipedia, except on your own talk page. <Learn more>

Attributes: Here are some key attributes for this notification:

Trigger: Administrator action
Main Link: this page (wikis can override it to provide a different link that explains policy for each user right, as listed below)
Payload: We may want to include the block rationale for blocked user right changes, as noted below
Frequency: One-time
Priority: High (mostly positive)
Category: System Message

Notes:

This notification proposal is not planned for the first release of Echo but could be developed in future releases.
To make this notification even more meaningful, it would be great if we could include the block rationale as payload, if it's under N characters.

Huggle Notifications

Once we have an external API, we have the opportunity to hook into third-party anti-vandalism tools like Huggle (or ClueBot). Some of these tools could be adapted to provide a "Mark as useful" button (Huggle already has such a button), which could send a notification to the user who made the 'good' edit saying something like:

'Kaldari marked your edit as useful for Golden-crowned Sparrow. <View your edit>'

This would require us to provide a hook (or API) to the third-party developers, but it's actually a lot less work than having to find some other trigger in MediaWiki for it to take its cues off, and has a better signal:noise ratio than any trigger we've yet discussed.

While this seems like a reasonable solution to investigate, it may not be a viable candidate for Echo's first release, because the hooks / API requirements and coordination with third-party developers are likely to take several months to set up.

Reply to Talkpage Message

Workflow: Talkpage reply

This notification occurs when someone replies to a message you left on their talkpage:

Jimbo replied to your post on <their talk page>:
"You are welcome. I completely agree with you".

Trigger: User edit on other talkpage section you started
Main Link: Talk page (to edited section, if possible)
Payload: Show 'Edit summary'
Frequency: High
Priority: High
Category: Talk page message

Started Page - Talkpage Message

This notification occurs when someone leaves a message on the talk page of a page you started:

Knowledgekid87 posted on <the talk page> of <Transcarpathian Art Institute>.
"Good first stab. Have you considered expanding the history section?"

Trigger: User edit on talkpage of article you started
Main Link: Talk page (to edited section, if possible)
Payload: Show 'Edit summary' (or 'New section first line')
Frequency: Medium
Priority: Medium
Category: Talk page message

Contributions since your last edit

This notification would occur when other editors contribute to a page you recently edited (and your edit survived).

5 editors contributed to <Porcelain money> since your last edit.

Here are some of this notification's parameters:

Trigger: User edits (with no revert)
Main Link: Article page
Payload: None
Frequency: High

While this type of activity is currently handled by the watchlist, this type of 'contributions' notification could have a positive impact in getting the new user to go back to a page they edited earlier (particularly if they don't yet feel motivated to use the watchlist). This is almost certainly better than only sending them negative notifications when their edits are reverted (which is like a slap in the face) -- or sending them no notifications whatsoever after their first edits (which is what we are doing now).

However, this particular notification idea may not always have a positive impact if the user's previous edit was manually reverted or overwritten, which we cannot easily detect, sadly. Also, this would only work for new users with low levels of activity, and could quickly become overwhelming for more active users. In order to address this issue, it may be possible to define a threshold that would only send a notification that 'x people have contributed to this page' if x exceeds a certain percentage y of the total number of editors for this page (e.g.: y = 20%? ). (Note that this notification could be based on the number of edits to that page, instead of editors, if that is easier for development purposes.)

From a technical standpoint, this is a hard feature to develop, as it would require generating Echo events for every edit on Wikipedia for every editor of every article (even if they are bundled or filtered to a certain group of users), which could quickly explode the database -- and also likely crash the servers with massive numbers of expensive queries. For that reason, we cannot develop it in our first release, but are open to considering it again for future releases.

Check out your watchlist

This notification occurs when your watchlist has new activity, and is aimed at new users, to get them to use the watchlist more. The notification might look like this:

'Check out <your watchlist>: it has 15 new changes this week.'

This notification could be sent once a week for the first three months after a new user's registration (or it could be sent only if they have not visited their watchlist in more than x days, if feasible).

The rationale for this notification is that most new users forget that they have a watchlist and do not get in the habit of checking it regularly until they become active. This feature would keep nudging them to check it out, and encourage this important habit over time.

This feature is a bit more complex than [#How_to_use_your_watchlist|'How to use your watchlist']] (see above), but would be a good candidate if we have the bandwith to develop more notifications after the initial release.

If keeping track of 'new' changes proves difficult to implement, we could simply remove the word 'new' and just let the users know how many changes are now listed on their watchlist, which should be easier to extract.

Here are some key attributes for this notification:

Trigger: either weekly (up to 3 months after your first edit?) -- or 1 week since your last visit
Main Link: watchlist page
Payload: None
Frequency: Medium
Priority: High (useful to new users)
Category: Watchlist
Flyout Summary: [icon] 'Check out <your watchlist>: it has 15 new changes this week.'
All-notifications Summary: [icon] 'Check out <your watchlist>: it has 15 new changes this week.'
Email Subject: Check out your watchlist on Wikipedia
Email Summary: 'Check out <your watchlist>: it has 15 new changes this week.' [could add a bit more copy if needed]
Web preference default: Enabled for new editors, disabled for experienced editors
Email preference default: Enabled for new editors, disabled for experienced editors
Web bundling: Disabled
Email bundling: Disabled
Dismiss feature: Enabled

Special requirements: This notification would only be enabled by default for new editors. It could be sent weekly (for up to 3 months after your first edit?), but a better implementation would be to send it if you haven't visited the watchlist in over a week -- and if there are new items that you haven't seen yet.

Our team agreed that this feature is a bit too complex for our first release, because it requires a lot of experimentation to get it right. But we would like to see it developed in future releases, if we can get development resources from either the E2 or E3 team.

Answer to your question

This notification occurs when your question is answered (in Help / Teahouse/ Moodbar).

Kaldari answered a question you asked in <Teahouse>.

Trigger: User edit (in section you started on helpdesk page)
Main Link: Helpdesk page (to edited section, if possible)
Payload: Show 'Edit summary' (or 'answer first line'?)
Frequency: Low

Watched Page - Feedback

This notification occurs when a page you watch features useful feedback:

<Feedback> about <Tamalpais Valley> was marked as useful by Quiddity.
"Nice article, but it would be great if you could add a map and expand the history."

Here are some key attributes for this notification:

Trigger: Feedback marked as 'useful' by an editor
Main Link: Feedback page for your page (showing new post on top of 'featured' list)
Payload: Show comment that was just marked as useful -- e.g. the first 30? words of that comment, as shown below:

"Nice article, but it would be great if you could add a map and expand the history."

Frequency: High
Priority: Medium (neutral)
Category: Feedback
Flyout Summary: [icon] <Feedback> about Tamalpais Valley was marked as useful by Quiddity.
Archive Summary: [icon] <Feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
Email Subject 1: A page you watch has feedback on Wikipedia
Email Summary: <Feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
HTML Email Button: <View feedback>

Notes:

This notification would only take place on projects which have Article Feedback enabled (e.g.: English or French Wikipedias)
For this reason, we consider this to be an infrequent notification, even though it is likely to be constructive for some editors
We recommend implementing this 'Watched Page Feedback' notification instead of the 'Started Page Feedback' option below, because many community members have requested a method for informing editors about feedback posted on their watched pages.
For now, we propose to only let them know if feedback was marked useful (rather than if new feedback was posted), because that makes it valuable to the most people without overwhelming them with too many notifications for this experimental feature.
This notification should be bundled, so you only get notifications about feedback on the same watched page every 4 hours or so, after the first one.
Feedback notifications should be opt-in for current users (disabled by default for both web and email notifications) -- but opt-out for new users (enabled by default for both web and email notifications)

Featured Feedback

This notification occurs when feedback you posted is marked as useful (or resolved) by an editor:

Your <feedback> about <Tamalpais Valley> was marked as useful by Quiddity.
"Nice article, but it would be great if you could add a map and expand the history."

Here are some key attributes for this notification:

Trigger: Feedback marked as 'useful' by an editor
Main Link: Feedback page for your comment (showing that post on top of 'featured' list)
Payload: Show comment that was just marked as useful -- e.g. the first 30? words of that comment, as shown below:

"Nice article, but it would be great if you could add a map and expand the history."

Frequency: Low
Priority: Medium (positive)
Category: Feedback
Flyout Summary: [icon] Your <feedback> about Tamalpais Valley was marked as useful by Quiddity.
Archive Summary: [icon] Your <feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
Email Subject 1: Your feedback was found useful on Wikipedia
Email Summary: Your <feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
HTML Email Button: <View feedback>

Notes:

This notification would only take place on projects which have Article Feedback enabled (e.g.: French or German Wikipedias)
This notification would only be sent to registered users, which means anonymous readers who post feedback would not get it
For the reasons above, we consider this to be an infrequent and low priority notification, even though it is likely to have a very positive effect
Feedback notifications should be opt-in for current users (disabled by default for both web and email notifications) -- but opt-out for new users (enabled by default for both web and email notifications)

Started Page - Feedback

Note: We recommend holding off on this 'Started Page Feedback' notification idea -- and implementing instead the 'Watched Page Feedback' option above, because many community members have requested a method for informing editors about feedback posted on their watched pages -- which would cover most important use cases for page creators and potentially duplicate the Watched page functions.

This notification would occurs when a page you started features useful feedback:

<Feedback> about <Tamalpais Valley> was marked as useful by Quiddity.
"Nice article, but it would be great if you could add a map and expand the history."

Here are some key attributes for this notification:

Trigger: Feedback marked as 'useful' by an editor
Main Link: Feedback page for your page (showing new post on top of 'featured' list)
Payload: Show comment that was just marked as useful -- e.g. the first 30? words of that comment, as shown below:

"Nice article, but it would be great if you could add a map and expand the history."

Frequency: High
Priority: Medium (neutral)
Category: Feedback
Flyout Summary: [icon] <Feedback> about Tamalpais Valley was marked as useful by Quiddity.
Archive Summary: [icon] <Feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
Email Subject 1: A page you watch has feedback on Wikipedia
Email Summary: <Feedback> about <Tamalpais Valley> was marked as useful by <Quiddity>.
HTML Email Button: <View feedback>

Notes:

This notification would only take place on projects which have Article Feedback enabled (e.g.: French or German Wikipedias)
For this reason, we consider this to be an infrequent notification, even though it is likely to be constructive for some editors
As stated above, we recommend holding off on this notification until a later date
Feedback notifications should be opt-in for current users (disabled by default for both web and email notifications) -- but opt-out for new users (enabled by default for both web and email notifications)

Started Page - Today's Featured Article

This notification occurs when a page you started is Today's Featured Article:

<Nancy Drew> is Today's Featured Article.

Trigger: Not sure
Main Link: Your page (or Main Page?)
Payload: None
Frequency: Low
Priority: Very High (positive)
Category: Recognition

Note: This would only happen very rarely, so we are putting this notification on hold for now.

Features under consideration

These features are being considered for Echo. Some of them will be included in the first release, others in future releases.

Dismiss

New designs under review for the Dismiss feature

Dismiss flyout detail - current version

The 'Dismiss' tool will enable users to turn off notifications they don't want to see in the flyout or the all-notifications page, so they don't have to go to the preferences page if they don't want to.

Purpose: The purpose of this feature is to give users more control over the notifications they receive, so they can:

quickly turn off or delete notifications they don't want
do this in the flyout or the all-notifications page

We are exploring new designs for this Dismiss feature, to improve the previous version that was tested on MediaWiki.org in early 2013, as shown in thumb|these slides. These designs are being discussed with the Echo team and community members, to evaluate their merits and feasibility. Once we settle on a direction, we will update these feature requirements accordingly. For now, the rest of this section describes the previous version, which has since been removed from MediaWiki.org because of concerns that it might confuse new users.

Functions: Dismiss flyout workflow - current version

Dismiss all-notifications workflow

Here is how the dismiss feature would work, as shown in the mockups to the right:

When the user hovers over a notifications, a gray "(x)" button appears on the right side.
When the user clicks on that "x" button, the notification is replaced with "Turn off all 'Edit Reverted' notifications?", with a "Turn off" button and "Cancel" link
- If the user clicks "Turn off", disable both web and email user preference for that notification type, and show this message: "You have turned off 'Edit Reverted' notifications. <Undo>"
- If the user clicks "Turn off", show the notification again and do nothing else.
- If the user clicks "Undo", show the notification again and do nothing else.
Once the user turns off a particular notification type, all notifications of this type will be dynamically removed from the flyout and all-notifications page AND from all email notifications
This means that both web and email notification checkboxes will be disabled for that notification type in the user preferences
If later on the user wants to re-enable a dismissed notification type, they can do this in preferences

Exceptions: The dismiss button would not be available for certain types of notifications which are considered critical and time-sensitive, such as:

talk page messages
system notifications (e.g. your user rights have changed)
onboarding (e.g. welcome, check out your watchlist)

These notifications cannot be dismissed and no 'X' button will appear when you mouse over them in the flyout or all-notifications page.

Best Practices: Here are some examples of how this dismiss feature is implemented on other sites like Facebook:

Watchlist features

This section is about interactions between Echo and the watchlist, which are intended to work together as a system for surfacing things that happen on MediaWiki and Wikipedia sites.

Our team deliberately identified certain items as out of scope for Echo, since they would be covered by the watchlist. For example, we didn't see a need to send an Echo notification for every item that appears in the watchlist, to avoid redundancy. In general, we view the watchlist as providing ambient awareness about lots of minor events, while Echo is intended to notify the user about important events that impact the user directly.

That said, we would like to make the watchlist (and the "notifications" inherent in the watchlist) more visible to new users, who may not be aware that this tool even exists -- or may not be motivated to check it, since it is empty when they first register. So we need to at a minimum let new users know that the watchlist exists and potentially make some preference changes to make watchlists easier to use.

Here are some of the possible ways we can ensure that new users are aware that 1) they have a watchlist and/or 2) there are new items in that watchlist. The first couple features below seem like likely candidates for the first release, while the others are more likely to be considered for future releases.

Watchlist notifications: These watchlist notifications are listed separately from features, in the notification section for features:

How to use your watchlist (scheduled for the first release)
Check your watchlist (held back for future releases)

Add edited pages to new user watchlist

If you are a new user, this feature will automatically add pages that you edit or start to your watchlist.

The rationale for doing this is to fill in new users' watchlists based on their recent edits, so they can find this tool more valuable and start using it more often.

This could be simply implemented by changing the default for new users to automatically check the current Watchlist preference called 'Add pages and files I edit to my watchlist.'

If a user wants to stop this from happening at any time, they can turn off that preference.

Note: Someone has already a proposed revision for this feature, which is awaiting review. So we could simply approve or tweak that revision, then merge it ourselves. Ask Steven Walling for more details (see also bug 45020).

Watchlist guided tour

This feature would show a guided tour to new users, the first time they visit their watchlist.

It is scheduled for the first release of Echo, and is intended to work with the How to use your watchlist notification and the Add edited pages to new user watchlist feature.

The WMF Editor Experimentation team (E3) will develop this feature as part of their new user onboarding project.

This feature will offer the following benefits:

explain what the watchlist is for
invite users to click on the star button to add items to their watchlist
show them how to switch between watched articles and recent changes

This guided tour will appear 1) after the user makes a first edit (which will add the article they just edited to their previously empty watchlist); 2) the first time the user visits the now-filled watchlist; and 3) when the user receives the 'How to use your watchlist' notification. This would link to the watchlist page, where a guided tour would greet them.

Special requirements:

This guided tour would only be shown once (though a small 'What is this?' link could be included on the watchlist page, in case they want to see it again).
It would only be shown if the user has already made at least one edit (which would automatically add the pages they edited to their watchlist, thanks to the related 'Add pages to new user watchlists' feature).
By default, we would show the 'All watched' tab first when the guided tour starts (see mockup).
Note: We considered pre-filling your watchlist with a few articles so we could show the guided tour earlier in the new user's lifecycle, but ruled this out for now, because it would be inconsistent with the current behavior.

Watchlist filters redesign mockup

Watchlist page filters

The watchlist page itself could be improved to make it simpler and less overwhelming for new users. Maryana and Vibha have prepared this mockup to show how the watchlist filters at the top of the page could be improved with just a few simple changes.

While this feature seems like an easy and obvious improvement, some experienced users might prefer the current layout, which they are already comfortable with. So this would require that we discuss these changes with community members first (and/or that we only make the improvements available to new users (with an opt-in preference for current users).

We agreed that this is not a must-have for the first release, but that we would try to fit it in shortly after, if we can get development resources for this simple improvement.

Note:

If a guided tour is available for this page, we may want to consider a small 'What is this?' link somewhere on the watchlist page, in case they need to see it again.

Other watchlist feature ideas

Here are some other ideas which we considered, but postponed for future releases.

Watchlist counter: A third way is to put a little counter next to the watchlist link in the user menu, so they can see there are new items from any page they visit on Wikipedia.
Watchlist popups: Another idea that has been suggested would pop a notification saying there are new events in the watchlist until the new user has clicked n times on the watchlist (default off for experienced editors), until the user builds a habit.

Talk Counter

We have discussed the idea of offering a separate counter for the 'Talk' link that appears in the user menu, so that users know the number of unread messages they have on their talk page. The rationale for this proposed feature is to make it easier for people to find out about these personal messages, which could otherwise get lost in a stream of lower-priority notifications. We also discussed adding a flyout for this Talk links, where notifications could be listed separately from the main notifications flyout, but concluded that this would raise too many issues, making it impractical for the first release. For example, people are now used to clicking on the 'Talk' link to go to the talk page, and would resent having to click twice to go there. Also, there will inevitably be some dependencies with 'Flow', our upcoming user-to-user messaging product, and it seems better to hold off on developing a new talk notification features until that new product is further along.

API

Once Echo is further along, we plan to provide an API allowing 3rd parties to send notifications (rather than just extensions using hooks). The rationale is that other developers could expand on some of the basic notification framework we are now working on, without requiring the WMF to develop all new notifications. But this would also require us to develop a set of policies governing their use, to prevent folks from spamming our users. It's going to be a challenge to find the right policies to support both goals, and these policies will require extensive deliberations with the Wikipedia community. This is inevitably going to be a major project, both on the technical and community fronts, and is therefore out of scope for our first release. For now, we will continue to research our options, as well as review best practices from other popular platforms that provide a Notifications API to developers, such as Facebook (see their API overview and design guidelines) and Android. (Note that Facebook tracks whether notifications sent by third parties with their API are meeting certain thresholds in terms of clickthrough and uses that data to weed out low-performing or spammy notifications.)

Echo Notification Storage

Job queues are not generally persistent, but the system needs to both deliver notifications to users in a timely manner, and also present previously sent notifications for later viewing. This means that as well as putting new notifications into a queue, the system also needs to add them to a persistent mailbox store.

This persistent mailbox store will need to support two very different types of notifications:

critical notifications such as talk page or system messages, which need to be stored persistently and cannot be flushed
transient notifications such as page links or mentions, which are not critical and can be flushed after a period of time

Persistent talk page notifications are critical to support the workflows of Wikipedia. Even a single missed notification can cause disruption to the project, for example, if a request for an administrator to protect a page or block a user is missed. Many Wikipedia users only login from time to time, and need to be notified about talk messages, even if it's been months since their last login. This is how the current message notification tool works today, and the community will not react kindly to a lapse in this functionality. It's also worth noting that best practices on top sites like Facebook, Google or Twitter is to keep message-related notifications forever as well.

For those reasons, we recommend that critical notifications be stored forever (if a time limit is essential for technical reasons, we recommend they be kept for at least one year, and that we discuss this with the community before reaching a final decision). On the other hand, transient notifications could be purged after at a while (until we hear from the community on this issue, we recommend keeping them for at least a month, if feasible).

This is an important distinction, because the Redis technology we are now considering for this persistent storage mailbox is not designed for long term storage of rarely fetched older data. So for storage of 'critical' notifications, we may want to use MySQL instead, as it can provide reliable long term storage, even though its performance may be slower than Redis.

One proposal for addressing this issue would be to use Redis as the default mailbox storage, but critical notifications would be cached to MySQL (e.g. talk page messages and system messages). This would keep the bulk of notifications in Redis, with failover to the MySQL store if needed.

Metrics

We plan to measure the impact of this notifications project through a variety of metrics. To learn more, please read this metrics plan.

Here are the first dashboards and studies we are developing for the first release of Echo on the English Wikipedia in April 2013.

Related documents

Notifications/Feature requirements

Overview

Problems & Solutions

Guidelines

User groups

Key features

User Menu

Flyout

Message indicator

All notifications

Email notifications

Individual Email Notifications

Plain text email notifications

Sample Message - Single Notification

Message Contents

Header Contents

Subject contents

Body Contents

Footer Contents

HTML single email notifications

Email Digests

Plain text email digests

HTML email digests

Other email specifications

Preferences

Email settings

Notification Settings

Message Indicator Preference

Defaults by User Group

Other Email Preferences

Special Features

Bundling

JobQueue

Mark all as read

Blacklist

Improved Notification Structure

Purpose

Improvements

Text snippet

Notification Types

Notification Groups

Notification Categories

Icons and types

First Notifications

Interactive

Talkpage Message

User Mention

Positive

Thank you notification

File Used

More positive notifications

Neutral

Started Page - Marked as reviewed

Started Page - Tagged

Started Page - Linked

Negative

Started Page - Marked for deletion

Edit reverted

New user notifications

Welcome

Getting started

Power user notifications

User rights

Blocked user post

Started Page - Rated

Started Page - Featured

Started Page - WikiProject

Under consideration

How to use your watchlist

WikiLove

Autoconfirmed notification

Blocked user notification

Huggle Notifications

Reply to Talkpage Message

Started Page - Talkpage Message

Contributions since your last edit

Check out your watchlist

Answer to your question

Watched Page - Feedback

Featured Feedback