Update/review documentation and examples

[kputnam]

The API documentation at rubydoc.info is probably in decent shape, but I'm not sure if the YARD plugins are still working.

The human-readable documentation in doc/ could be stale. It might be time to update it, and maybe publish it somewhere else like readthedocs.io

Things to review:

• README.md
• examples/
• notes/
• API documentation
• doc/
• usage messages in bin/ and examples/