use better examples, fix formatting

use better examples - user id 404 might be mistaken for an http status code, and 'song:played' is a more realistic action (to most people).

Also fix formatting (this file is using restructured text, not markdown, but github does not render admonitions properly).

README.rst

@@ -19,14 +19,11 @@ Bitter can answer following questions:
 * How many % of users that were active last week are still active?
 * How many % of users that were active last month are still active this month?
 
-Bitter is very easy to use and enables you to create your own reports easily.
-
-.. note::
-    Please look `Bitter <http://bitter.free-agent.fr/>`_ website for more info and documentation about this project.
+Bitter is very easy to use and enables you to create your own reports easily - see the `Bitter Library <http://bitter.free-agent.fr/>`_ website for more info and documentation about this project.
 
 Installation
 ------------
-Use `Composer <https://github.com/composer/composer/>`_ to install: `free-agent/bitter`.
+Use `Composer <https://github.com/composer/composer/>`_ to install: ``free-agent/bitter``.
 
 In your `composer.json` you should have:
 
@@ -40,8 +37,7 @@ In your `composer.json` you should have:
 
 Bitter uses `Redis <http://redis.io>`_ (version >=2.6).
 
-.. note::
-    Every keys created in `Redis` will be prefixed by `bitter:` ; temp keys by `bitter_temp:`.
+**Note**: Every key created in Redis will be prefixed by ``bitter:``, temp keys by ``bitter_temp:``.
 
 Basic usage
 -----------
@@ -52,46 +48,44 @@ Create a Bitter with a Redis client (Predis as example):
     $redisClient = new \Predis\Client();
     $bitter = new \FreeAgent\Bitter\Bitter($redisClient);
 
-Mark user 404 as active and has been kicked by Chuck Norris:
+Mark user 123 as active and has played a song:
 
 .. code-block:: php
 
-    $bitter->mark('active', 404);
-    $bitter->mark('kicked_by_chuck_norris', 404);
-
-.. note::
+    $bitter->mark('active', 123);
+    $bitter->mark('song:played', 123);
 
-    Please don't use huge ids (e.g. 2^32 or bigger) cause this will require large amounts of memory.
+**Note**: Please don't use huge ids (e.g. 2^32 or bigger) cause this will require large amounts of memory.
 
 Pass a DateTime as third argument:
 
 .. code-block:: php
 
-    $bitter->mark('damned_by_jack_bauer', 404, new \DateTime('yesterday'));
+    $bitter->mark('song:played', 123, new \DateTime('yesterday'));
 
-Test if user 404 as been kicked by Chuck Norris this week:
+Test if user 123 has played a song this week:
 
 .. code-block:: php
 
-    $currentWeek = new FreeAgent\Bitter\Event\Week('kicked_by_chuck_norris');
+    $currentWeek = new FreeAgent\Bitter\Event\Week('song:played');
 
-    if ($bitter->in(404, $currentWeek) {
-        echo 'User with id 404 has been kicked by Chuck Norris this week.';
+    if ($bitter->in(123, $currentWeek) {
+        echo 'User with id 123 has played a song this week.';
     } else {
-        echo 'User with id 404 has not been kicked by Chuck Norris this week.';
+        echo 'User with id 123 has not played a song this week.';
     }
 
-How many users have been active yesterday:
+How many users were active yesterday:
 
 .. code-block:: php
 
     $yesterday = new \FreeAgent\Bitter\Event\Day('active', new \DateTime('yesterday'));
 
-    echo 'Yesterday: ' . $bitter->count($yesterday) . ' users has been active.';
+    echo $bitter->count($yesterday) . ' users were active yesterday.';
 
 Using BitOp
 -----------
-How many users that were active yesterday are active today:
+How many users that were active yesterday are also active today:
 
 .. code-block:: php
 
@@ -102,12 +96,11 @@ How many users that were active yesterday are active today:
         ->bitOpAnd('bit_op_example', $today, $yesterday)
         ->count('bit_op_example')
     ;
-    echo $count . ' were active yesterday are active today.';
+    echo $count . ' were active yesterday and today.';
 
-.. note::
-    The `bit_op_example` key will expire after 60 seconds.
+**Note**: The ``bit_op_example`` key will expire after 60 seconds.
 
-Test if user 13 was active yesterday and is active today:
+Test if user 123 was active yesterday and is active today:
 
 .. code-block:: php
 
@@ -116,16 +109,15 @@ Test if user 13 was active yesterday and is active today:
 
     $active = $bitter
         ->bitOpAnd('bit_op_example', $today, $yesterday)
-        ->in(13, 'bit_op_example')
+        ->in(123, 'bit_op_example')
     ;
     if ($active) {
-        echo 'User 13 was active yesterday and today.';
+        echo 'User 123 was active yesterday and today.';
     } else {
-        echo 'User 13 was not active yesterday and today.';
+        echo 'User 123 was not active yesterday and today.';
     }
 
-.. note::
-    Please look at `Redis BITOP Command <http://redis.io/commands/bitop>`_ for performance considerations.
+**Note**: Please look at `Redis BITOP Command <http://redis.io/commands/bitop>`_ for performance considerations.
 
 Unit Tests
 ----------