doc review and improvements