Docs overhaul

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