Revise Why use venv/bin/pip instead of source bin/activate then pip?

- Closes #2610

1 files changed, 14 insertions, 9 deletions

diff --git a/docs/narr/install.rst b/docs/narr/install.rst
index 7b5d8361b..570cb2285 100644
--- a/docs/narr/install.rst
+++ b/docs/narr/install.rst
@@ -199,15 +199,20 @@ After installing Python as described previously in :ref:`for-mac-os-x-users` or
 .. note:: Why use ``$VENV/bin/pip`` instead of ``source bin/activate``, then
    ``pip``?
 
-   Although the latter method requires fewer key strokes to issue commands once
-   invoked, there are numerous reasons why one should avoid using ``activate``
-   within a virtual environment. Michael F. Lamb (datagrok) presents a summary
-   in `Virtualenv's bin/activate is Doing It Wrong
-   <https://gist.github.com/datagrok/2199506>`_, and proposes alternatives,
-   followed by comments from other developers.
-
-   However, we prefer to keep things simple. ``$VENV/bin/pip`` is already
-   UNIX-y. The few extra key strokes are worth avoiding the mess altogether.
+   ``$VENV/bin/pip`` clearly specifies that ``pip`` is run from within the
+   virtual environment and not at the system level.
+
+   ``activate`` drops turds into the user's shell environment, leaving them
+   vulnerable to executing commands in the wrong context. ``deactivate`` might
+   not correctly restore previous shell environment variables.
+
+   Although using ``source bin/activate``, then ``pip``, requires fewer key
+   strokes to issue commands once invoked, there are other things to consider.
+   Michael F. Lamb (datagrok) presents a summary in `Virtualenv's bin/activate
+   is Doing It Wrong <https://gist.github.com/datagrok/2199506>`_.
+
+   Ultimately we prefer to keep things clear and simple, so we use
+   ``$VENV/bin/pip``.
 
 
 .. index::