some readability improvements in doc