update docs with @pieterv's feedback