clarify docs and make url to them nicer