diff --git a/docs/guides/upgrading.rst b/docs/guides/upgrading.rst
index 45830e5136d..928e8e2f525 100644
--- a/docs/guides/upgrading.rst
+++ b/docs/guides/upgrading.rst
@@ -207,6 +207,70 @@ Example of the new way:
 
     See how the community_plugins plugin was updated to use the new system: https://github.com/Elgg/community_plugins/commit/bfa356cfe8fb99ebbca4109a1b8a1383b70ff123
 
+Notifications can also be sent with the ``notify_user()`` function.
+
+It has however been updated to support three new optional parameters passed inside an array as the fifth parameter.
+
+The parameters give notification plugins more control over the notifications, so they should be included whenever possible. For example the bundled site_notifications plugin won't work properly if the parameters are missing.
+
+Parameters:
+
+-  **object** The object that we are notifying about (e.g. ElggEntity or ElggAnnotation). This is needed so that notification plugins can provide a link to the object.
+-  **action** String that describes the action that triggered the notification (e.g. "create", "update", etc).
+-  **summary** String that contains a summary of the notification. (It should be more informative than the notification subject but less informative than the notification body.)
+
+Example of the old way:
+
+.. code:: php
+
+	// Notify $owner that $user has added a $rating to an $entity created by him
+
+	$subject = elgg_echo('rating:notify:subject');
+	$body = elgg_echo('rating:notify:body', array(
+		$owner->name,
+		$user->name,
+		$entity->title,
+		$entity->getURL(),
+	));
+
+	notify_user($owner->guid,
+				$user->guid,
+				$subject,
+				$body
+			);
+
+Example of the new way:
+
+.. code:: php
+
+	// Notify $owner that $user has added a $rating to an $entity created by him
+
+	$subject = elgg_echo('rating:notify:subject');
+	$summary = elgg_echo('rating:notify:summary', array($entity->title));
+	$body = elgg_echo('rating:notify:body', array(
+		$owner->name,
+		$user->name,
+		$entity->title,
+		$entity->getURL(),
+	));
+
+	$params = array(
+		'object' => $rating,
+		'action' => 'create',
+		'summary' => $summary,
+	);
+
+	notify_user($owner->guid,
+				$user->guid,
+				$subject,
+				$body,
+				$params
+			);
+
+.. note::
+
+    Compatible with 1.8
+
 Adding items to the Activity listing
 ------------------------------------
 
diff --git a/engine/lib/notification.php b/engine/lib/notification.php
index 05aa63fc6fb..91b1fd147fa 100644
--- a/engine/lib/notification.php
+++ b/engine/lib/notification.php
@@ -363,6 +363,20 @@ function _elgg_notify_user($to, $from, $subject, $message, array $params = null,
  * @param string $subject          Message subject.
  * @param string $message          Message body.
  * @param array  $params           Misc additional parameters specific to various methods.
+ *
+ *                                 By default Elgg core supports three parameters, which give
+ *                                 notification plugins more control over the notifications:
+ *
+ *                                 object => null|ElggEntity|ElggAnnotation The object that
+ *                                           is triggering the notification.
+ *
+ *                                 action => null|string Word that describes the action that
+ *                                           is triggering the notification (e.g. "create"
+ *                                           or "update").
+ *
+ *                                 summary => null|string Summary that notification plugins
+ *                                            can use alongside the notification title and body.
+ *
  * @param mixed  $methods_override A string, or an array of strings specifying the delivery
  *                                 methods to use - or leave blank for delivery using the
  *                                 user's chosen delivery methods.