diff --git a/doc/source/debugging.rst b/doc/source/debugging.rst
new file mode 100644
index 0000000..b0e0450
--- /dev/null
+++ b/doc/source/debugging.rst
@@ -0,0 +1,29 @@
+=================
+ Debugging Tests
+=================
+
+Running tests through testrepository_ makes it difficult to use pdb for
+debugging them. oslotest includes ``oslo_debug_helper`` to make using
+pdb simpler/possible.
+
+First, add a pdb call to the test code::
+
+  import pdb; pdb.set_trace()
+
+Then run the tests through ``oslo_debug_helper`` like
+
+::
+
+  $ oslo_debug_helper [tests to run]
+
+or
+
+::
+
+  $ tox -e venv -- oslo_debug_helper [tests to run]
+
+.. seealso::
+
+   * https://wiki.openstack.org/wiki/Testr
+
+.. _testrepository: https://pypi.python.org/pypi/testrepository
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2e3f9b0..40186ad 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,6 +9,7 @@
    testing
    features
    cross-testing
+   debugging
    resources
    contributing