Documentation fixes / review

Do not merge this yet, but feel free to review and comment.