doc: tweak the written style a little and tidy up the rst