some small updates for readability
cherry picking from gh-pages