diff --git a/README.asciidoc b/README.asciidoc
index 3df054a88..777af1807 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -49,6 +49,7 @@ image:http://qutebrowser.org/img/cheatsheet-small.png["qutebrowser keybinding ch
 * link:doc/HACKING.asciidoc[HACKING]
 * link:doc/INSTALL.asciidoc[INSTALL]
 * link:doc/stacktrace.asciidoc[Reporting segfaults]
+* link:doc/userscripts.asciidoc[How to write userscripts]
 
 Getting help
 ------------
diff --git a/doc/help/index.asciidoc b/doc/help/index.asciidoc
index 5925e615d..0ff537e72 100644
--- a/doc/help/index.asciidoc
+++ b/doc/help/index.asciidoc
@@ -10,6 +10,7 @@ The following help pages are currently available:
 * link:FAQ.html[Frequently asked questions]
 * link:commands.html[Documentation of commands]
 * link:settings.html[Documentation of settings]
+* link:userscripts.html[How to write userscripts]
 
 Getting help
 ------------
diff --git a/doc/userscripts.asciidoc b/doc/userscripts.asciidoc
new file mode 100644
index 000000000..5734e0e63
--- /dev/null
+++ b/doc/userscripts.asciidoc
@@ -0,0 +1,64 @@
+Writing qutebrowser userscripts
+===============================
+The Compiler <mail@qutebrowser.org>
+
+qutebrowser is extensible by writing userscripts which can be called via the
+`:spawn --userscript` command, or via a keybinding.
+
+These userscripts are similiar to the (non-javascript) dwb userscripts. They
+can be written in any language which can read environment variables and write
+to a FIFO.
+
+Note for simple things such as opening the current page with another browser or
+mpv, a simple keybinding to something like `:spawn mpv {url}` should suffice.
+
+Also note userscripts need to have the executable bit set (`chmod +x`) for
+qutebrowser to run them.
+
+Getting information
+-------------------
+
+The following environment variables will be set when an userscript is launched:
+
+- `QUTE_MODE`: Either `hints` (started via hints) or `command` (started via
+  command or keybinding).
+- `QUTE_USER_AGENT`: The currently set user agent.
+- `QUTE_FIFO`: The FIFO or file to write commands to.
+
+In `command` mode:
+
+- `QUTE_URL`: The current URL.
+- `QUTE_TITLE`: The title of the current page.
+- `QUTE_SELECTED_TEXT`: The text currently selected on the page.
+- `QUTE_SELECTED_HTML` The HTML currently selected on the page.
+
+In `hints` mode:
+
+- `QUTE_URL`: The URL selected via hints.
+- `QUTE_SELECTED_TEXT`: The plain text of the element selected via hints.
+- `QUTE_SELECTED_HTML` The HTML of the element selected via hints.
+
+Sending commands
+----------------
+
+Normal qutebrowser commands can be written to `$QUTE_FIFO` and will be
+executed.
+
+On Unix/OS X, this is a named pipe and commands written to it will get executed
+immediately.
+
+On Windows, this is a regular file, and the commands in it will be executed as
+soon as your userscript terminates. This means when writing multiple commands,
+you should append to the file (`>>` in bash) rather than overwrite it (`>`).
+
+Examples
+--------
+
+Opening the currently selected word on http://www.dict.cc/[dict.cc]:
+
+[source,bash]
+----
+#!/bin/bash
+
+echo "open -t http://www.dict.cc/?s=$QUTE_SELECTED_TEXT" >> "$QUTE_FIFO"
+----
diff --git a/scripts/asciidoc2html.py b/scripts/asciidoc2html.py
index a9069519e..12730a0e6 100755
--- a/scripts/asciidoc2html.py
+++ b/scripts/asciidoc2html.py
@@ -71,6 +71,7 @@ def main(colors=False):
     asciidoc_files = [
         ('doc/FAQ.asciidoc', 'qutebrowser/html/doc/FAQ.html'),
         ('doc/quickstart.asciidoc', 'qutebrowser/html/doc/quickstart.html'),
+        ('doc/userscripts.asciidoc', 'qutebrowser/html/doc/userscripts.html'),
     ]
     try:
         os.mkdir('qutebrowser/html/doc')