README.md in botolo-0.10.0 vs README.md in botolo-0.20.0

@@ -1,8 +1,10 @@
 # Botolo
 
-TODO: Write a gem description
+Botolo is an engine for bots written in ruby. With botolo you must take care
+only about writing actions your bot must implement and then the engine will
+execute them for you.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
@@ -16,10 +18,103 @@
 
     $ gem install botolo
 
 ## Usage
 
-TODO: Write usage instructions here
+For creating a great bot you have to describe in a YAML configuration file the
+Bot behaviour and in a separate ruby class you must implement the methods your
+bot must carry on.
+
+Let's see how to create a very dummy bot saying _foo_ every 3 seconds and
+saying _hello_ every 5 seconds. 
+
+You have to write a config.yaml file containing the action schedule and some
+very basic information about your bot.
+
+``` 
+verbose: true
+
+bot:
+  name: dummy-bot
+  version: 1.0
+  email: [e-mail]
+  # This overrides any behaviour file passed as argument
+  behaviour: dummy-bot.rb
+
+twitter:
+  enabled: no
+task:
+  - { schedule: every 5 s, action: say_hello }
+  - { schedule: every 3 s, action: say_foo }
+``` 
+
+Botolo expects to find in the current directory a file named dummy-bot.rb
+implementing the two methods (say\_hello and say\_foo) it has to run based upon
+this schedule. 
+There is a **big** constraint: your ruby file must be a Botolo::Bot::Behaviour
+class. It must also implement an initialize method with an Hash parameter
+engine will use to pass options to the bot.
+
+It will be used in the future to implement some form of communication between
+the main process and threads, useful to provide a centralized console about
+what's going on on your bot.
+
+Let's see our dummy bot behaviour:
+
+``` 
+module Botolo
+  module Bot
+    class Behaviour
+      def initialize(options={})
+      end
+
+      def say_hello
+        puts "hello"
+      end
+
+      def say_foo
+        puts "foo"
+      end
+    end
+  end
+end
+``` 
+
+It's easy, isn't it!?! 
+
+Now, all you have to do is running the botolo command specifying the config
+file as parameter. Remember to put the behaviour class in the same directory of
+your YAML file.
+
+``` 
+$ botolo config.yaml
+botolo:9: warning: already initialized constant OpenSSL::SSL::VERIFY_PEER 
+[*] dummy-bot v1.0 is starting up at 08:31:31
+08:31:31: 2 tasks loaded
+08:31:31: using ./dummy-bot.rb as bot behaviour
+08:31:31: dummy-bot is online
+08:31:31: entering main loop
+08:31:31: hello
+08:31:31: foo
+08:31:34: foo
+08:31:36: hello
+08:31:37: foo
+08:31:40: foo
+08:31:41: hello
+08:31:43: foo
+^C08:31:46: shutting down threads
+08:31:46: pid #<Thread:0x007fa731022e18> killed
+08:31:46: pid #<Thread:0x007fa731022cd8> killed
+[*] bot is shutting down at 08:31:46
+``` 
+
+Custom written behaviour can use the global variable $logger to use botolo logging
+facilities and having the stdout/stderr prints more consistent.
+
+## Missing features
+
+A back channels for threads to communicate with the engine about action
+status.
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)