Fixed examples, lots more documentation

The examples weren't working for a few reasons. I fixed those and also

* converted from decking.json to decking.yaml -- easier to read, but even more importantly lets us comment the file
* Commented the example decking.yaml
* Added lots more documentation to the README.