first cut on improved documentation, just headlines and started on some description
tidy up readme
Merge branch 'documentation'