rose documentation: update following feedback

We've received (and created) some more feedback for the documentation.