better docs

@charlierudolph this is inspired by one of your comments. Please take a look!  :)
In my opinion 

* the command name gives a one-word summary of the command. 
* The one-line summary gives a high-level overview of the command. The command name is already known at this point, so repeating it here is redundant and doesn't add understanding. Saying the same thing in a different way, using a synonym, is helpful.
* The description gives all the details and steps.