updates to documentation, link to docs in README, fixes for typos and inconsistencies