Update docs to implement @parkr's suggestions