The purpose of this page is to serve as the central point of discussion for developing a grammarfor notifications.

The Echo project will need to serve many different types of events. A grammar system will help manage complexity, both from a user experience perspective as well as a technical perspective. It will help ensure consistency throughout the system.

(Apologies if the terms used don't match conventional terms from English Grammar).

Examples from other sites[edit]


Here are the some notifications on Facebook, starting with the simplest examples:

  • Bill and Jim like your status: "This is my status"
  • Jill commented on your Wall Post: "Thanks!"
  • John added a new photo.
  • Bob shared a link: <link>
  • Michelle, Cynthia and Steve commented on Shen's photo.

In these examples, there is:

  • a piece of Content (e.g., status, post, photo, link)
  • an Action taken (e.g., liked, added, shared, commented on)
  • an Actor who takes the action on the piece of content (e.g., Bill, Jill, John)

Grammatically, this is Subject-Verb-Object:

  • John (subject) added (verb) a new photo (object).

Here's a slightly more complicated example:

  • Jane likes a photo on her timeline.

The location of the photo ("where can someone find this photo") is explicitly added. (I think "on her timeline" is a prepositional phrase that serves to as an adjective for photo?)

Note: sometimes the location of the photo is implied:

  • Jon added a new photo [to his timeline].


Alfredo Martinez wrote an answer for the question Stanford University: Who are considered the biggest star-faculty members at Stanford?

Subject-Verb-Direct Object-Indirect Object? Noun-Verb-Noun (Person-Action-Object)


Most(?) actions on Wikipedia involve a piece of content (e.g., you edit the Breakfast article). Even direct user-to-user interactions involve a piece of content (e.g., someone writes on your talk page).

Here are some examples of notifications for some different scenarios:


Example: Howie edits the article Breakfast. Fabrice reverts his edit. The following could be notifications that show up in Howie's notifications stream:

  1. Fabrice edited Breakfast.
  2. Fabrice reverted your edit to Breakfast.

The first case would probably be simpler to implement since there is no relationship between Fabrice's edit and Howie's.


Example: Vibha creates Breakfast page, Ryan deletes the page. (in Vibha's notifications)

  1. Ryan deleted Breakfast.

Deletion Template

Example: Vibha creates Breakfast page, Ryan applies deletion template (in Vibha's notifications)

  1. Ryan edited Breakfast. (adding deletion template is an edit)
  2. Ryan added a template to Breakfast. (specifes that Ryan's edit is the addition of a template, but not which template was added)
  3. Ryan added {{subst:Proposed deletion|concern=article sucks}} to Breakfast. (specifies the type of template Ryan added).

Adding a category

Example: Benny watches the Dog article, Fabrice adds the category "Animals" to the article. (In Benny's notifications)

  1. Fabrice edited Dog.
  2. Fabrice added a category to Dog.
  3. Fabrice added the category "Animals" to Dog (or Fabrice adds "Dog" to the category "Animal").


Example: Ryan mentions Benny on a Village Pump discussion (in Benny's notifications)

  1. Ryan mentioned you in <Village Pump discussion:>