diff --git a/doc/bugs/JSON_output_broken_with___34__git_annex_sync__34__.mdwn b/doc/bugs/JSON_output_broken_with___34__git_annex_sync__34__.mdwn
index 00a4c22376..f0809c568b 100644
--- a/doc/bugs/JSON_output_broken_with___34__git_annex_sync__34__.mdwn
+++ b/doc/bugs/JSON_output_broken_with___34__git_annex_sync__34__.mdwn
@@ -16,3 +16,6 @@ Expecting valid JSON, instead this happens:
 What version of git-annex are you using? On what operating system?
 
 Newest standalone (3.20121126), Linux i386. The "json_reformat" program is from the "yajl-tools" .deb package.
+
+> [[done]]; I've updated the --json documentation to note that it only
+> works with some query commands. --[[Joey]] 
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 7646e43928..5a69fe496f 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -522,7 +522,8 @@ subdirectories).
 
   Rather than the normal output, generate JSON. This is intended to be
   parsed by programs that use git-annex. Each line of output is a JSON
-  object.
+  object. Note that json output is only usable with some git-annex commands,
+  like status and find.
 
 * --debug