README.md in boty-0.0.7 vs README.md in boty-0.0.9

@@ -129,12 +129,59 @@
 
  **todo: document**
 
 For now, check the `script/ping.rb` and follow it's leads.
 
+### Describing script usage
+
+A bot list all the commands and message handlers that it knows in the moment. If
+you want to give a nice description and/or a usage tip on command you can use
+the `desc` method.
+
+Given that your bot has the following script:
+
+```ruby
+desc "pug me", "Send some nice pug in the channel."
+respond(/pug me/i) do
+  # ...
+end
+```
+
+The follow text will be part of the response for a `@bot: knows` command:
+
+    pug me: Send some nice pug in the channel.
+
+You can use just the description if you want. In this case the `regex` itself
+will be used as the command name.
+
+```ruby
+desc "Send some nice pug in the channel."
+respond(/pug me/i) do
+  # ...
+end
+```
+
+    valeriano 2:25PM
+    @bot: knows
+
+    bot 2:25PM
+        knows: List all the commands known by this bot.
+    /pug me/i: Send some nice pug in the channel.
+
+We strongly recommend that you describe all of your scripts. But if you don't,
+the bot will be capable of tell you what `regexes` are binded to it:
+
+    valeriano 2:47PM
+    @jabberu: knows
+
+    jabberu 2:47PM
+                          knows: List all the commands known by this bot.
+                      /pug me/i
+    /jabberu, are you there\?/i
+
 ### Testing your own scripts
 
- **todo: document**`
+ **todo: document**
 
 For now, check the `spec/script/ping_spec.rb` and follow it's leads.
 
 ## Development