update docs to be more clear/representative