diff --git a/docs/changelog.rst b/docs/changelog.rst
index 81493428c..b8bdc15cc 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -6,6 +6,9 @@ Changelog
 
 Features:
 
+* Verbosity is now an integer in the configuration since multiple levels are
+  supported (like e.g. apt-get). On the CLI one can stack verbose flags (i.e.
+  `-vv`). :bug:`1244`
 * The summary shown to compare duplicate albums during import now displays
   the old and new filesizes. :bug:`1291`
 * The colors used are now configurable via the new config option ``colors``,
@@ -106,7 +109,9 @@ For developers:
 
 * The logging system in beets has been overhauled. Plugins now each have their
   own logger, which helps by automatically adjusting the verbosity level in
-  import mode and by prefixing the plugin's name. Also, logging calls can (and
+  import mode and by prefixing the plugin's name.  Logging levels are
+  dynamically set when a plugin is called, depending on how it is called
+  (import stage, event or direct command).  Finally, logging calls can (and
   should!) use modern ``{}``-style string formatting lazily. See
   :ref:`plugin-logging` in the plugin API docs.
 * A new ``import_task_created`` event lets you manipulate import tasks
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index 97da193f0..f448b5dfa 100644
--- a/docs/dev/plugins.rst
+++ b/docs/dev/plugins.rst
@@ -480,14 +480,21 @@ str.format-style string formatting. So you can write logging calls like this::
 .. _PEP 3101: https://www.python.org/dev/peps/pep-3101/
 .. _standard Python logging module: https://docs.python.org/2/library/logging.html
 
-The per-plugin loggers have two convenient features:
+When beets is in verbose mode, plugin messages are prefixed with the plugin
+name to make them easier to see.
+
+What messages will be logged depends on the logging level and the action
+performed:
+
+* On import stages and event, the default is ``WARNING`` messages.
+* On direct actions, the default is ``INFO`` and ``WARNING`` message.
+
+The verbosity can be increased with ``--verbose`` flags: each flags lowers the
+level by a notch.
+
+This addresses a common pattern where plugins need to use the same code for a
+command and an import stage, but the command needs to print more messages than
+the import stage. (For example, you'll want to log "found lyrics for this song"
+when you're run explicitly as a command, but you don't want to noisily
+interrupt the importer interface when running automatically.)
 
-* When beets is in verbose mode, messages are prefixed with the plugin name to
-  make them easier to see.
-* Messages at the ``INFO`` logging level are hidden when the plugin is running
-  in an importer stage (see above). This addresses a common pattern where
-  plugins need to use the same code for a command and an import stage, but the
-  command needs to print more messages than the import stage. (For example,
-  you'll want to log "found lyrics for this song" when you're run explicitly
-  as a command, but you don't want to noisily interrupt the importer interface
-  when running automatically.)
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index e569c073c..f889be678 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -369,7 +369,7 @@ import ...``.
 * ``-l LIBPATH``: specify the library database file to use.
 * ``-d DIRECTORY``: specify the library root directory.
 * ``-v``: verbose mode; prints out a deluge of debugging information. Please use
-  this flag when reporting bugs.
+  this flag when reporting bugs. It can be stacked twice.
 * ``-c FILE``: read a specified YAML :doc:`configuration file <config>`.
 
 Beets also uses the ``BEETSDIR`` environment variable to look for