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




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:>