diff --git a/doc/bugs/set_metadata_on_wrong_files.mdwn b/doc/bugs/set_metadata_on_wrong_files.mdwn
index add68bae50..e317147840 100644
--- a/doc/bugs/set_metadata_on_wrong_files.mdwn
+++ b/doc/bugs/set_metadata_on_wrong_files.mdwn
@@ -86,3 +86,5 @@ metadata c.txt
   num=3
 ok
 """]]
+
+> [[fixed|done]]; documentation improved --[[Joey]]
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 6e9f39826c..51f618d0a6 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -711,8 +711,9 @@ subdirectories).
 
 * `metadata [path ...] [-s field=value -s field+=value -s field-=value ...] [-g field]`
 
-  Each file can have any number of metadata fields attached to it,
-  which each in turn have any number of values. 
+  The content of a file can have any number of metadata fields 
+  attached to it to describe it. Each metadata field can in turn
+  have any number of values. 
   
   This command can be used to set metadata, or show the currently set
   metadata.
diff --git a/doc/metadata.mdwn b/doc/metadata.mdwn
index 9f3c314fa2..684820cb95 100644
--- a/doc/metadata.mdwn
+++ b/doc/metadata.mdwn
@@ -1,7 +1,7 @@
-git-annex allows you to store arbitrary metadata about files stored in the
-git-annex repository. The metadata is stored in the `git-annex` branch, and
-so is automatically kept in sync with the rest of git-annex's state, such
-as [[location_tracking]] information.
+git-annex allows you to store arbitrary metadata about the content of files
+stored in the git-annex repository. The metadata is stored in the
+`git-annex` branch, and so is automatically kept in sync with the rest of
+git-annex's state, such as [[location_tracking]] information.
 
 Some of the things you can do with metadata include: