diff --git a/docs/debugging.md b/docs/debugging.md
new file mode 100644
index 000000000..0ea50af9a
--- /dev/null
+++ b/docs/debugging.md
@@ -0,0 +1,52 @@
+# Debugging
+
+## Looking Glass
+
+[Looking Glass][lg] is a built-in debugger and inspector tool that makes
+it possible to run arbitrary JS code inside the shell, visually select
+any object from the shell's scene, and much more.
+
+It can be accessed by entering `lg` into the run dialog (Alt+F2).
+
+[lg]: looking-glass.md
+
+## Javascript stacktraces
+
+gnome-shell is split between C and JavaScript. It is sometimes necessary
+to debug the interaction between the two, for example when javascript
+code triggers a warning or crash on the C side.
+
+In gdb, the javascript stacktrace can be printed with
+```
+<gdb> gjs_dumpstack()
+```
+
+The `SHELL_DEBUG` environment variable can be used to print
+the javascript stack automatically:
+
+ * `backtrace-warning`: when a warning is logged
+ * `backtrace-segfault`: on segfaults
+
+To log a stacktrace when some particular javascript code is reached, you
+can insert the following code:
+
+```js
+console.trace('trace from doSomething()')
+```
+
+## Debugging the session's gnome-shell proces
+
+It is possible to attach gdb to the gnome-shell process of the existing
+login session (or with the native backend on a tty), but beware: When the
+debugger stops the gnome-shell process, the entire session will freeze.
+
+It is necessary to use a second system to continue controlling the
+debugger, most conveniently in combination with [screen]:
+
+ 1. create a screen session
+ 2. detach the session
+ 3. ssh from a second system
+ 4. resume the screen session
+ 5. attach gdb to the gnome-shell process
+
+[screen]: https://www.gnu.org/software/screen/