Better documentation

[KnVerey]

• Improve readme (better explanation of core functionality and options, screenshots)
• Convert all existing comment-based docs to rdoc or yard
• Add comment-based docs for the key methods you need to use the tasks from Ruby instead of from the CLI (i.e. the run and run! methods of each Task class).

[kirs]

We use yard in Shopify core. Maybe it would make sense to use it here too.

[KnVerey]

Ideas for more readme enhancements:

• Description of a few workflows like:
  • Getting started - using stuff from an 'examples' directory
  • Walk through the steps of a deploy
• GIF screen recording of terminal running a deploy locally - put this right near the top of the readme

[KnVerey]

• Readme should reference a directory of examples, even if it is just our test fixtures

[dirceu]

After #581 and #582, do we need anything else?

I'm not sure about this:

Convert all existing comment-based docs to rdoc or yard

There aren't many comments, and most are specific to a particular condition inside a method, etc.

[KnVerey]

I'm inclined to agree now that only thing we need to document with yard are the public interfaces.