diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f2a1287
--- /dev/null
+++ b/README.md
@@ -0,0 +1,17 @@
+# Description
+This repository contains the set of files that are used to build a custom 
+MOTD message for the SCITAS clusters.
+
+# Layout
+The `fragments` file is fetched first and then each line in that file is used
+as a basename for fetching the individual fragments.
+
+For each fragment there is a hierarchy, more specific wins:
+1. <fragment name>
+1. <fragment name>.<cluster name> (taken from the config file)
+1. <fragment name>.<hostname>
+
+The content of each fragment is fetched in the same order and concatenated
+into a single file: `/etc/scitas.motd`.
+
+If configured this file is displayed at login time.