diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..7696b0319c1b203a8561efe0dc80f4def3275027
--- /dev/null
+++ b/README.md
@@ -0,0 +1,28 @@
+# Files
+
+All configuration is to be placed inside the `filaes` dict.
+This dict is a <key>:<value> mapping. With <key> being the path of a file, for example
+'/boo/bar'. <value> is a *fileconfig* dict, see below.
+
+**fileonfig**
+```
+# file owner
+owner: root
+
+# file group
+group: root
+
+# permission bits, can be octal number or the string representation
+mode: 0700
+
+# can be 'present', 'absent', 'directory', or 'touch' (ensure file is created and set modification time to now, but do not change the content)
+state:  present
+
+# set the file content, mutaly exclusive with "template". Only handeled if the state if 'file'
+content: ''
+
+# not yet implemented
+template: ~
+template_vars: ~
+
+```