I feel a bit of the documentation might be misleading and not always that great to go over.

Instead of adding more and more the README, I think we should (w/in the REPO) start to write a guide/book on HOWTO.

Regarding the actual format, I think asciidoc comes to mind;

Any thoughts ? 

 
--
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf