diff --git a/docs/source/development/messaging.txt b/docs/source/development/messaging.txt
index 5b150a5..e3088c2 100644
--- a/docs/source/development/messaging.txt
+++ b/docs/source/development/messaging.txt
@@ -808,8 +808,7 @@ Message type: ``display_data``::
 
         # The data dict contains key/value pairs, where the kids are MIME
         # types and the values are the raw data of the representation in that
-        # format. The data dict must minimally contain the ``text/plain``
-        # MIME type which is used as a backup representation.
+        # format.
         'data' : dict,
 
         # Any metadata that describes the data
@@ -817,6 +816,24 @@ Message type: ``display_data``::
     }
 
 
+The ``metadata`` contains any metadata that describes the output.
+Global keys are assumed to apply to the output as a whole.
+The ``metadata`` dict can also contain mime-type keys, which will be sub-dictionaries,
+which are interpreted as applying only to output of that type.
+Third parties should put any data they write into a single dict
+with a reasonably unique name to avoid conflicts.
+
+The only metadata keys currently defined in IPython are the width and height
+of images::
+
+    'metadata' : {
+      'image/png' : {
+        'width': 640,
+        'height': 480
+      }
+    }
+
+
 Raw Data Publication
 --------------------