diff --git a/README.md b/README.md
index a87cec5..11bd669 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,4 @@
-# smash
+# smash — SMS Mail Alarm Sending Helper
+
+The configuration is described in [`recipients.cfg` ](recipients.cfg) and [`rules.cfg`](rules.cfg).
 
diff --git a/recipients.cfg b/recipients.cfg
index 43938b4..ef02091 100644
--- a/recipients.cfg
+++ b/recipients.cfg
@@ -1,2 +1,6 @@
+# list of recipients
+# may contain email adresses and phone numbers for SMS
+# comments via # are allowed
+
 sven.augustin@psi.ch
 0123456789 # not actually a phone number
diff --git a/rules.cfg b/rules.cfg
index 1a57be3..ad3ea20 100644
--- a/rules.cfg
+++ b/rules.cfg
@@ -1,3 +1,7 @@
+# list of alarm rules
+# they follow the form: PVNAME COMPARISON VALUE
+# comments via # are allowed
+
 MTEST:COUNTER1 > 0.5 # test
 MTEST:COUNTER2 < 0.5