docs: document bad shebangs in Python scripts

Author: indygreg

docs/quirks.rst

@@ -4,6 +4,23 @@
 Behavior Quirks
 ===============
 
+Bad Shebangs in Python Scripts
+==============================
+
+Various Python scripts under ``install/bin/`` (e.g. ``pip``) have
+shebangs looking like ``#!/build/out/python/install/bin/python3``.
+This ``/build/out/`` directory is where the distribution is built
+from. Python is writing out shebangs for Python scripts with
+that absolute path.
+
+To work around this issue, you can mass rewrite the shebangs to
+point the directory where the distribution is extracted/installed
+to.
+
+Alternatively, you can sometimes execute ``python3 -m <module>``
+to get equivalent functionality to what the installed script would
+do. e.g. to run pip, ``python3 -m pip ...``.
+
 Backscape Key Doesn't work in Python REPL
 =========================================