new file mode 100644
--- /dev/null
+++ b/testing/marionette/doc/Debugging.md
@@ -0,0 +1,64 @@
+Debugging
+=========
+
+Redirecting the Gecko output
+----------------------------
+
+The most common way to debug Marionette, as well as chrome code in
+general, is to use `dump()` to print a string to stdout.  In Firefox,
+this log output normally ends up in the gecko.log file in your current
+working directory.  With Fennec it can be inspected using `adb logcat`.
+
+`mach marionette test` takes a `--gecko-log` option which lets
+you redirect this output stream.  This is convenient if you want to
+“merge” the test harness output with the stdout from the browser.
+Per Unix conventions you can use `-` (dash) to have Firefox write
+its log to stdout instead of file:
+
+	% ./mach marionette test --gecko-log -
+
+This debugging technique can be particularly effective when combined
+with using [pdb] in the Python client or the JS remote debugger
+that is described below.
+
+[pdb]: https://docs.python.org/2/library/pdb.html
+
+
+JavaScript debugger
+-------------------
+
+You can attach a JavaScript debugger to the Marionette server
+through the [Browser Toolbox].  This enables you to introspect and
+set breakpoints in Gecko chrome code, which is a far more powerful
+debuggin technique than using `dump()` or `console.log()`.
+
+The browser toolbox can be opened automatically when running Mn
+tests by passing `--jsdebugger` to the mach command:
+
+	% ./mach marionette test --jsdebugger
+
+It will prompt you when to start the test run to allow you time to
+set your breakpoints.  It will also prompt you between each test.
+
+For reference, below is the list of preferences that enables the
+chrome debugger for Marionette.  These are all set implicitly when
+`--jsdebugger` is passed to mach.  In non-official builds, which
+are the default when built using `./mach build`, you will find that
+the chrome debugger won’t prompt for connection and will allow
+remote connections.
+
+  * `devtools.debugger.prompt-connection` → true
+
+    Controls the remote connection prompt.  Note that this will
+    automatically expose your Firefox instance to the network.
+
+  * `devtools.chrome.enabled` → true
+
+    Enables debugging of chrome code.
+
+  * `devtools.debugger.remote-enabled` → true
+
+    Allows a remote debugger to connect, which is necessary for
+    debugging chrome code.
+
+[Browser Toolbox]: https://developer.mozilla.org/en-US/docs/Tools/Browser_Toolbox

--- a/testing/marionette/doc/Intro.md
+++ b/testing/marionette/doc/Intro.md
@@ -53,27 +53,27 @@ need to download a Marionette client or 
 
   * [Using Marionette via WebDriver][1]
   * [Download and setup the Python client for Marionette][2]
   * [Run Tests with Python][3] – How to run tests using the
     Python client
   * You might want to experiment with [using Marionette interactively
     at a Python command prompt][3]
   * Start [writing and running][4] tests with supported test frameworks!
-  * [Debugging server][5] code using the Browser Toolbox
+  * Tips on [debugging][5] Marionette code
   * [Get a Build][6] – Instructions on how to get a Marionette-enabled
     build of Firefox
   * [Download and setup the Marionette JS client][7]
   * [Protocol definition][8]
 
 [1] https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/WebDriver
 [2] http://marionette-client.readthedocs.io/en/latest/
 [3] http://marionette-client.readthedocs.io/en/latest/interactive.html
 [4] https://developer.mozilla.org/en/Marionette/Tests
-[5] https://developer.mozilla.org/en-US/docs/Marionette/Debugging
+[5] ./Debugging.md
 [6] https://developer.mozilla.org/en-US/docs/Marionette/Builds
 [7] https://github.com/mozilla-b2g/marionette_js_client
 [8] https://developer.mozilla.org/en-US/docs/Mozilla/QA/Marionette/Protocol
 
 
 Bugs
 ====