MRG: Doc improvements

This is a small PR that addresses some details of the documentation and examples . It is true that documentation needs a larger refactoring, but this will be the topic of future PRs.