diff --git a/README.rst b/README.rst
index 0a3473b..21b63c6 100644
--- a/README.rst
+++ b/README.rst
@@ -19,3 +19,15 @@ Usage
 pip install reviewstats
 
 Run the scripts.
+
+Project definitions
+-------------------
+
+Each project has a JSON file describing what reviews, bugs and so on will count
+towards that projects statistics. The JSON file should have a single top level
+object containing the following keys:
+
+* name: The project name.
+* subprojects: A list of Gerrit projects to include
+* core-team: A list of Gerrit usernames to consider as core reviewers across
+  subprojects.