better docs

@charlierudolph this is inspired by one of your comments. Please take a look!  :)