refreshed docs to reflect the latest crucial change