Move usage docs out of README and into godoc.

Minor style updates to the prose.
Document Error type