update for documentation reorganization

As part of our documentation restructuring sprint this week, Simon has abstracted a lot of this out into the github.io documentation on branch gh-pages, and I've edited this page for clarity, in line with other github project README files.