is this a good idea? maybe a series of md files, or a gh-pages documentation instead? I think this would clear up the read-me a bit and allow for some more in-depth examples.