docs update and fixes as suggested by @zachshallbetter