PEP 646: Make explicit some more considerations of the motivation (#1881)

pep-0646.rst

@@ -33,7 +33,7 @@ large impact, and the main case this PEP targets - concerns typing in
 numerical libraries.
 
 In the context of numerical computation with libraries such as NumPy and TensorFlow,
-the *shape* of arguments is often just as important as the argument *type*.
+the *shape* of variables is often just as important as the variable *type*.
 For example, consider the following function which converts a batch [#batch]_
 of videos to grayscale:
 
@@ -51,8 +51,22 @@ and
 
   time × batch × channels × height × width. [#timebatch]_
 
-Ideally, we should have some way of making the required shape clear in the
-signature itself. Multiple proposals [#numeric-stack]_ [#typing-ideas]_
+This is important for three reasons:
+
+* **Documentation**. Without the required shape being clear in the signature,
+  the user must hunt in the docstring or the code in question to determine
+  what the input/output shape requirements are.
+* **Catching shape bugs before runtime**. Ideally, use of incorrect shapes
+  should be an error we can catch ahead of time using static analysis.
+  (This is particularly important for machine learning code, where iteration
+  times can be slow.)
+* **Preventing subtle shape bugs**. In the worst case, use of the wrong shape
+  will result in the program appearing to run fine, but with a subtle bug
+  that can take days to track down. (See `this exercise`_ in a popular machine learning
+  tutorial for a particularly pernicious example.)
+
+Ideally, we should have some way of making shape requirements explicit in
+type signatures. Multiple proposals [#numeric-stack]_ [#typing-ideas]_
 [#syntax-proposal]_ have suggested the use of the standard generics syntax for
 this purpose. We would write:
 
@@ -781,6 +795,8 @@ References
 
 .. _mrahtz/cpython/pep637+646: https://github.com/mrahtz/cpython/tree/pep637%2B646
 
+.. _this exercise: https://spinningup.openai.com/en/latest/spinningup/exercise2_2_soln.html
+
 Copyright
 =========