Rewrite the docs to fit the current best practices for Puppetlabs

modules.

FIRST DRAFT for discussion.

We're experimenting with adding type/allowed values in the README, so I've tried that here (to help us improve testing).