Misc docs suggestions

It seems I'm not the right person to change this text as I don't see what's wrong with it and your comment contradicts it. Please tell me what you want it to say so I can add another patch or modify it later after merging.