rewrote parts of docs to be more thorough