diff --git a/README.md b/README.md
new file mode 100644
index 0000000..393730f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+ensure
+======
+
+Ensure is a small library to help ensure state on a UNIX system. It is
+currently pretty basic and doesn't have much to offer apart from a
+file/directory and exec helper.
+
+But with these small pieces more should easily be possible and go offers more
+than enough to implement other functions on top of the ensurer interface and
+the runner to ensure the state.
+
+how to use
+----------
+
+To use this library use one of the provided resources or implement one yourself
+with the Ensurer interface.
+
+Either call Ensure on the resource yourself or let one of the runners do it
+for all your resources.
+
+```
+package main
+
+import (
+  "io/ioutil"
+  "os"
+  "path"
+
+  "git.zero-knowledge.org/gibheer/ensure"
+  "git.zero-knowledge.org/gibheer/ensure/file"
+)
+
+func main() {
+  tmpDir, _ := ioutil.TempDir("", "")
+  defer os.RemoveAll(tmpDir)
+  f := &file.F{
+    Path: path.Join(tmpDir, "test")
+  }
+  if !f.Is() {
+    if err := f.Ensure(); err != nil {
+      fmt.Fatalf("could not ensure file: %s\n", err)
+    }
+  }
+
+  // Use a runner to ensure multiple resources blocked by a check.
+  // In case of the runner, ensure will also run Is() before making changes.
+  // Better read the documentation, not all resources do that or can do that.
+  r := &ensure.Runner{
+    States: []ensure.Ensurer{f},
+    Is: f.Is,
+  }
+  if err := r.Ensure(); err != nil {
+    fmt.Fatalf("could not ensure directory: %s", err)
+  }
+}
+```