Docs overhaul

continuation of #1039

TODO :  

  - [x] add plugin name in "how to configure" sentences
  - [x] remove space before colon
  - [x] always a colon between the option name and the rest of the description
  - [x] have a more descriptive heading than "Usage" *when appropriate*
  - [x] be more descriptive for empty strings default