Remove confusing deprecation message

Deprecation message is a little premature as we don't have
a compelling alternative.  Also, cleans up the docs, for clarity.

Fixes #1531