--- a/python/mach/docs/usage.rst
+++ b/python/mach/docs/usage.rst
@@ -39,30 +39,50 @@ following are valid:
     $ ./mach help try fuzzy
     $ ./mach try -h
     $ ./mach try fuzzy --help
 
 
 Auto Completion
 ---------------
 
-A `bash completion`_ script is bundled with mach. To enable it with ``bash``,
-add the following to your ``~/.bashrc``, ``~/.bash_profile`` or equivalent:
+A `bash completion`_ script is bundled with mach, it can be used with either ``bash`` or ``zsh``.
+
+Bash
+~~~~
+
+Add the following to your ``~/.bashrc``, ``~/.bash_profile`` or equivalent:
 
 .. code-block:: shell
 
     source <srcdir>/python/mach/bash-completion.sh
 
-This script can also be used with ``zsh``. Add this to your ``~/.zshrc`` or
-equivalent:
+.. tip::
+
+    Windows users using the default shell bundled with mozilla-build should source the completion
+    script from ``~/.bash_profile`` (it may need to be created first).
+
+Zsh
+~~~
+
+Add this to your ``~/.zshrc`` or equivalent:
 
 .. code-block:: shell
 
-    autoload bashcompinit
-    bashcompinit
+    autoload -U bashcompinit && bashcompinit
+    source <srcdir>/python/mach/bash-completion.sh
+
+The ``compinit`` function also needs to be loaded, but if using a framework (like ``oh-my-zsh``),
+this will often be done for you. So if you see ``command not found: compdef``, you'll need to modify
+the above instructions to:
+
+.. code-block:: shell
+
+    autoload -U compinit && compinit
+    autoload -U bashcompinit && bashcompinit
     source <srcdir>/python/mach/bash-completion.sh
 
 Don't forget to substitute ``<srcdir>`` with the path to your checkout.
 
 
 User Settings
 -------------
 

--- a/tools/lint/codespell.yml
+++ b/tools/lint/codespell.yml
@@ -19,16 +19,17 @@ codespell:
         - layout/tools/layout-debug/ui/locale/en-US/
         - mobile/android/base/locales/en-US/
         - mobile/android/branding/
         - mobile/android/docs/
         - mobile/android/locales/en-US/
         - mobile/locales/en-US/
         - netwerk/locales/en-US/
         - python/docs/
+        - python/mach/docs/
         - python/mozlint/
         - python/safety/
         - services/sync/locales/en-US/
         - taskcluster/docs/
         - testing/mozbase/docs/
         - toolkit/components/extensions/docs/
         - toolkit/components/telemetry/docs/
         - toolkit/crashreporter/docs/