diff --git a/docs/source/OutputPlugins.rst b/docs/source/OutputPlugins.rst
index 6a643b88e8a6793a516260f96bd7986a4c56143e..d71ac1667e5de69d0d2f5a60018afb9606c810cf 100644
--- a/docs/source/OutputPlugins.rst
+++ b/docs/source/OutputPlugins.rst
@@ -62,6 +62,42 @@ simply use::
         </testcase>
         <testcase classname="synctest" name="synctest.1" time="1.69329714775"/>
 
+Machine readable output - json
+------------------------------
+
+`JSON <http://www.json.org/>`__ is a widely used data exchange format. The
+json avocado plugin outputs job information, similarly to the xunit output
+plugin::
+
+    $ scripts/avocado --json run "sleeptest failtest synctest"
+    {"tests": [{"test": "sleeptest.1", "url": "sleeptest", "status": "PASS", "time": 1.4282619953155518}, {"test": "failtest.1", "url": "failtest", "status": "FAIL", "time": 0.34017300605773926}, {"test": "synctest.1", "url": "synctest", "status": "PASS", "time": 2.109131097793579}], "errors": 0, "skip": 0, "time": 3.87756609916687, "debuglog": "/home/lmr/avocado/logs/run-2014-06-11-01.35.15/debug.log", "pass": 2, "failures": 1, "total": 3}
+
+Multiple output plugins
+-----------------------
+
+You can enable multiple output plugins at once, as long as only one of them
+uses the standard output. For example, it is fine to use the xunit plugin on
+stdout and the JSON plugin to output to a file::
+
+    $ scripts/avocado --xunit --json --json-output /tmp/result.json run "sleeptest synctest"
+    <?xml version="1.0" encoding="UTF-8"?>
+    <testsuite name="avocado" tests="2" errors="0" failures="0" skip="0" time="3.21392536163" timestamp="2014-06-11 01:49:35.858187">
+        <testcase classname="sleeptest" name="sleeptest.1" time="1.34533214569"/>
+        <testcase classname="synctest" name="synctest.1" time="1.86859321594"/>
+    </testsuite>
+
+    $ cat /tmp/result.json
+    {"tests": [{"test": "sleeptest.1", "url": "sleeptest", "status": "PASS", "time": 1.345332145690918}, {"test": "synctest.1", "url": "synctest", "status": "PASS", "time": 1.8685932159423828}], "errors": 0, "skip": 0, "time": 3.213925361633301, "debuglog": "/home/lmr/avocado/logs/run-2014-06-11-01.49.35/debug.log", "pass": 2, "failures": 0, "total": 2}
+
+But you won't be able to do the same without the --json-output flag passed to
+the program::
+
+    $ scripts/avocado --xunit --json run "sleeptest synctest"
+    Avocado could not set --json and --xunit both to output to stdout.
+    Please set the output flag of one of them to a file to avoid conflicts.
+
+That's basically the only rule you need to follow.
+
 Implementing other output formats
 ---------------------------------