diff --git a/README.rst b/README.rst
index 7db88c9..bb9c863 100644
--- a/README.rst
+++ b/README.rst
@@ -65,7 +65,7 @@ Changelog
 
 * *backwards incompatible* Guessing the file extension with the
   ``mimetypes`` package proved to be inconsistent across systems.
-  ``TemplatedEmailBackend`` now makes uses explicitly declared file
+  ``TemplatedEmailBackend`` now makes use of explicitly declared file
   extensions.
 
 **v0.2**
diff --git a/docs/index.rst b/docs/index.rst
index 9a09e14..2c9e709 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -149,3 +149,82 @@ Changelog
   - ``yell.decorators.yelling`` became ``yell.decorators.notification``
 
 
+====
+yell
+====
+
+Pluggable notifications for your Python apps. 
+
+`yell` is not a notification storage or delivery backend but a set of APIs that make it easy to add your own delivery mechanisms. 
+
+The full documentation is available `here <http://yell.readthedocs.org/en/latest/index.html>`_.
+
+
+Using notification decorators
+-----------------------------
+
+::
+
+    from yell import notify
+    from yell.decorators import notification
+    
+    @notification(name = 'buffalo')
+    def buffalo_printer(message):
+        print message
+    
+    @notification(name = 'buffalo')
+    def buffalo_saver(message):
+        save(message)
+        
+    notify("buffalo", _("Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo"))
+
+
+Using notification classes
+--------------------------
+
+::
+
+    from yell import Notification, notify
+
+    class Buffalo(Notification):
+        name = "buffalo"
+        message = _("Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo")
+        
+        def notify(self, *args, **kwargs):
+            print self.message
+        
+    class BuffaloEmail(Buffalo):
+        def notify(self, *args, **kwargs):
+            send_mail("Buffalo", self.message, 'buffalo@example.com', [kwargs.get('user').email])
+
+    class BuffaloDatabase(Buffalo):
+        def notify(self, *args, **kwargs):
+            BuffaloModel.objects.create(user = kwargs.get('user'))
+
+    # The default behaviour is to use every notification backend with the same 
+    # name 
+    notify("buffalo", user = User.objects.get(id=1))
+
+    # Only send emails
+    notify("buffalo", user = User.objects.get(id=1), backends = [BuffaloEmail])
+
+
+Changelog
+---------
+
+**v0.3**
+
+* *backwards incompatible* Guessing the file extension with the
+  ``mimetypes`` package proved to be inconsistent across systems.
+  ``TemplatedEmailBackend`` now makes use of explicitly declared file
+  extensions.
+
+**v0.2**
+
+* Made the API saner to use (*backwards incompatible*):  
+
+  - ``yell.Yell`` became ``yell.Notification``
+  - ``yell.yell`` became ``yell.notify``
+  - ``yell.decorators.yelling`` became ``yell.decorators.notification``
+
+