diff --git a/python/mach/docs/commands.rst b/python/mach/docs/commands.rst
index 5854c2deb5d3..24bec77d3dfd 100644
--- a/python/mach/docs/commands.rst
+++ b/python/mach/docs/commands.rst
@@ -38,16 +38,33 @@ Here is a complete example:
 .. rstcheck: ignore-languages=python
 .. code-block:: python
 
-    from mach.decorators import (
-      CommandArgument,
-      Command,
-    )
+   from mach.decorators import Command, CommandArgument
 
-    @Command('doit', help='Do ALL OF THE THINGS.')
+    @Command('doit', category='testing', description='Do ALL OF THE THINGS.')
     @CommandArgument('--force', '-f', action='store_true',
         help='Force doing it.')
     def doit(command_context, force=False):
         # Do stuff here.
+        print("hello world")
+
+All paths are relative to the root source folder.
+
+Save your file somewhere e.g. ``testing/doit.py``.
+
+Add an entry for your command in ``python/mach/mach/command_util.py`` in
+the `MACH_COMMANDS` dictionary. Maintain the alphabetical order.
+
+e.g
+
+.. code-block:: python
+
+    MACH_COMMANDS = {
+        # ... previous entries here
+        "doctor": MachCommandReference("python/mozbuild/mozbuild/mach_commands.py"),
+        "doit": MachCommandReference("testing/doit.py"),
+        "environment": MachCommandReference("python/mozbuild/mozbuild/mach_commands.py"),
+        # ... rest of entries here
+    }
 
 When the module is loaded, the decorators tell mach about all handlers.
 When mach runs, it takes the assembled metadata from these handlers and
@@ -89,9 +106,9 @@ Here is an example:
       """The build needs to be available."""
       return cls.build_path is not None
 
-  @Command('run_tests', conditions=[build_available])
-  def run_tests(command_context):
-      # Do stuff here.
+   @Command('run_tests', category='testing', description='A description.' conditions=[build_available])
+   def run_tests(command_context):
+       # Do stuff here.
 
 By default all commands without any conditions applied will be runnable,
 but it is possible to change this behaviour by setting