diff --git a/roles/openshift-apps/poddlers/README b/roles/openshift-apps/poddlers/README
new file mode 100644
index 0000000000..c560225e9e
--- /dev/null
+++ b/roles/openshift-apps/poddlers/README
@@ -0,0 +1,5 @@
+# Poddlers
+
+This is Toddlers running in pods. Each toddler has its own pod.
+
+You can add new toddlers and cronjobs by editing the `vars/apps/poddlers.yml` file. Please refer to the comments there for more info.
diff --git a/vars/apps/poddlers.yml b/vars/apps/poddlers.yml
index ea3de0b373..0bb3ed954a 100644
--- a/vars/apps/poddlers.yml
+++ b/vars/apps/poddlers.yml
@@ -1,4 +1,13 @@
 ---
+#
+# Toddlers
+#
+# List of running toddlers. Each has its own pod.
+# The format is a list of dicts, with each dict having the following schema:
+#   name: toddler name, needs to be unique
+#   callback: python path to the toddler class
+#   topics: list of topics to subscribe to, wildcards allowed.
+#
 poddlers_toddlers:
   - name: check-commit-rights
     callback: check_commit_rights:CheckCommitRights
@@ -82,6 +91,15 @@ poddlers_toddlers:
       - "org.fedoraproject.*.pagure.issue.edit"
       - "org.fedoraproject.*.pagure.issue.comment.added"
 
+#
+# Cronjobs
+#
+# List of cronjobs. It's a list of dicts in which each dict has the following schema:
+#   name: cronjob name, needs to be unique
+#   schedule: cron-like schedule
+#   only_env: only run this cronjob in the specified environment ("production" or "staging")
+#   command: the command to run
+#
 poddlers_cronjobs:
   - name: packager-bugzilla-sync
     schedule: "0 */6 * * *"