improve docs to make things clearer