Change recommendation about how to detect DeprecationWarningsformal-deprecation-notices

If you turn DeprecationWarnings into errors, code can stop just due to
python startup DeprectionWarnings - you'll never even get to your code!
It's much better just to allow DeprecationWarnings to bubble up.

2 files changed, 8 insertions, 6 deletions

diff --git a/README.rst b/README.rst
index 5f30e8c..2d4b4bb 100644
--- a/README.rst
+++ b/README.rst
@@ -430,10 +430,11 @@ code with the following flag
 
 .. code-block:: console
 
-    $ python -Werror::DeprecationWarning my-code.py
+    $ python -Wdefault::DeprecationWarning my-code.py
 
-This will turn any deprecation warnings into an error so that you can immediately
-find old APIs.
+By default ``DeprecationWarnings`` are not shown, but this will cause them to be shown.
+Alternatively, you can just set the environment variable ``PYTHONWARNINGS`` to
+"default::DeprecationWarning" and then run your code.
 
 Dropping Python 2.6 and 3.3 Support
 ===================================
diff --git a/docs/intro.rst b/docs/intro.rst
index 73635cd..03434f2 100644
--- a/docs/intro.rst
+++ b/docs/intro.rst
@@ -422,10 +422,11 @@ code with the following flag
 
 .. code-block:: console
 
-    $ python -Werror::DeprecationWarning my-code.py
+    $ python -Wdefault::DeprecationWarning my-code.py
 
-This will turn any deprecation warnings into an error so that you can immediately
-find old APIs.
+By default :exc:`DeprecationWarnings` are not shown, but this will cause them to be shown.
+Alternatively, you can just set the environment variable ``PYTHONWARNINGS`` to
+"default::DeprecationWarning" and then run your code.
 
 Dropping Python 2.6 and 3.3 Support
 ===================================