diff --git a/README.rst b/README.rst
index eeaad20..8260a2e 100644
--- a/README.rst
+++ b/README.rst
@@ -6,10 +6,13 @@ Persistent, stale-free cache / memoization decorators for Python.
 .. code-block:: python
 
   from cachier import cachier
+  import datetime
   
-  @cachier()
+  SHELF_LIFE = datetime.timedelta(days=3)
+  
+  @cachier(stale_after=SHELF_LIFE)
   def foo(arg1, arg2):
-    """Your function now has a persistent cache mapped by argument values!"""
+    """foo now has a persistent cache, trigerring recalculation for values stored more than 3 days!"""
     return {'arg1': arg1, 'arg2': arg2}
     
 
@@ -27,13 +30,26 @@ You can install cachier using:
 
     pip install cachier
 
+Features
+----------------------
+
+* A simple interface.
+* Defining "shelf life" for cached values.
+* Local caching using pickle files.
+* Cross-machine caching using MongoDB.
+* Thread-safety.
+
+Cachier is not:
+* Meant as a transient cache. Python's @lru_cache is better.
+* Especially fast. It is meant to replace function calls that take more than... a second, say (overhead is around 1 millisecond).
+
 
 Use
 ---
 
 Pickle-based Caching
 ~~~~~~~~~~~~~~~~~~~~
-You can add a deafult, pickle-based persistent cache to your function by decorating int with the `cachier` decorator (notice the `()`!).
+You can add a deafult, pickle-based persistent cache to your function by decorating it with the ``cachier`` decorator (notice the ``()``!).
 
 .. code-block:: python
 
@@ -44,7 +60,17 @@ You can add a deafult, pickle-based persistent cache to your function by decorat
     """Your function now has a persistent cache mapped by argument values!"""
     return {'arg1': arg1, 'arg2': arg2}
 
+Setting Shelf Live
+~~~~~~~~~~~~~~~~~~~~
+You can set any duration as the shelf life of cached return values of a function by providing a corresponding ``timedelta`` object to the ``stale_after`` parameter:
 
+.. code-block:: python
+
+  import datetime
+  
+  @cachier(stale_after=datetime.timedelta(weeks=2)
+  def bar(arg1, arg2):
+    return {'arg1': arg1, 'arg2': arg2}
 
 .. links:
 .. _bson package: https://api.mongodb.com/python/current/api/bson/