Improve docs, fixes #215
Tweak language following Luke's feedback
Merge pull request #217 from Financial-Times/docs

Improve docs, fixes #215