better docs

@charlierudolph this is inspired by one of your comments. Please take a look!  :)
I'm fine with this as is.