update docs based on @pescadorbob's feedback