PROPOSAL - general improvements

General changes, improvements and typo fixes.

- [ ] approve (PS, @HelenRoss, @justinhennessy, maybe @antfrew)
- [ ] peer review