update README.md, tidy up documentation, break details out separately