Improving docs / adding snippets

[ff6347]

As mentioned in #50 Would be great to have more examples. Even better would be to have simple "copy & pasteable" code snippets in the docs

[ff6347]

Stackoverflow is launching a new section called "Documentation" http://stackoverflow.com/tour/documentation What I found interesting about it is (besides al that other good stuff):

It's all about examples.

Examples illustrate common tasks or solutions to common problems - remember "Show, Don't Tell". A good example is self-contained and succinct, and more often than not contains code. It is more important that code in examples be illustrative and focused than that it be copy/paste-able; leave out boilerplate when it distracts from the concept the example is meant to illustrate.

leave out boilerplate when it distracts from the concept the example is meant to illustrate.

It is something to think about.