diff --git a/docs/plugins/fuzzy.rst b/docs/plugins/fuzzy.rst
index be659b386..604b0d998 100644
--- a/docs/plugins/fuzzy.rst
+++ b/docs/plugins/fuzzy.rst
@@ -1,25 +1,25 @@
 Fuzzy Search Plugin
 ===================
 
-The ``fuzzy`` plugin provides a command that search your library using
-fuzzy pattern matching. This can be useful if you want to find a track with complicated characters in the title.
+The ``fuzzy`` plugin provides a query prefix that search you library using fuzzy
+pattern matching. This can be useful if you want to find a track with
+complicated characters in the title.
 
 First, enable the plugin named ``fuzzy`` (see :doc:`/plugins/index`).
-You'll then be able to use the ``beet fuzzy`` command::
+You'll then be able to use the ``~`` prefix to use fuzzy matching::
 
-    $ beet fuzzy Vareoldur
+    $ beet ls '~Vareoldur'
     Sigur Rós - Valtari - Varðeldur
 
-The command has several options that resemble those for the ``beet list``
-command (see :doc:`/reference/cli`). To choose an album instead of a single
-track, use ``-a``; to print paths to items instead of metadata, use ``-p``; and
-to use a custom format for printing, use ``-f FORMAT``.
-
-The ``-t NUMBER`` option lets you specify how precise the fuzzy match has to be
-(default is 0.7). To make a fuzzier search, try ``beet fuzzy -t 0.5 Varoeldur``.
-A value of ``1`` will show only perfect matches and a value of ``0`` will match everything.
-
-The default threshold can also be set in the config file::
+The plugin provides to config option to let you choose the prefix and the
+threshold.::
 
     fuzzy:
         threshold: 0.8
+        prefix: '@'
+
+A threshold value of ``1`` will show only perfect matches and a value of ``0``
+will match everything.
+
+The default prefix ``~`` needs to be escaped or quoted in most shells. If this
+bothers you, you can change the prefix in your config file.
diff --git a/docs/plugins/writing.rst b/docs/plugins/writing.rst
index 6a18b8fbe..76f297f53 100644
--- a/docs/plugins/writing.rst
+++ b/docs/plugins/writing.rst
@@ -323,3 +323,34 @@ to register it::
             self.import_stages = [self.stage]
         def stage(self, config, task):
             print('Importing something!')
+
+Extend the Query Syntax
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Beets already support searching using regular expressions by prepending search
+terms with the colon prefix. It is possible to add new prefix by extending the
+``PluginQuery`` class.
+
+The plugin then need to declare its new queries by returning a ``dict`` of
+``{prefix: PluginQuery}`` insied the ``queries`` method.
+
+The following example plugins declares a query using the ``@`` prefix. So the
+plugin will be call if we issue a command like ``beet ls @something`` or
+``beet ls artist:@something``.::
+
+    from beets.plugins import BeetsPlugin
+    from beets.Library import PluginQuery
+
+    class ExampleQuery(PluginQuery):
+        def match(self, pattern, val):
+            return True # this will simply match everything
+
+    class ExamplePlugin(BeetsPlugin):
+        def queries():
+            # plugins need to declare theire queries by
+            # returning a dict of {prefix: PluginQuery}
+            # from the queries() function
+            return {
+                '@': ExampleQuery
+            }
+