diff --git a/overlay/README.md b/overlay/README.md
index b48b713..ab5f112 100644
--- a/overlay/README.md
+++ b/overlay/README.md
@@ -6,8 +6,10 @@ An overlay is constructed from a JSON file and, optionally, a markdown file cont
 
 ##JSON Format
 
-The JSON overlay file must include a name, manufacturer name, URL, description 
-( short description required, long is optional ) and a "pin" array.
+The JSON overlay file must include a name, manufacturer name, URL, description and a "pin" array defining all the
+pins that the board uses.
+
+If a counterpart .md file is present in description/overlay it will be used for the long description.
 
 The pin array must list each pin by its *physical* location, and include at least a "name" describing the function
 of that pin.