doc: review and improvements