Update the docs and add helpful notes.

Fixes #2577