diff --git a/README b/README
new file mode 100644
index 0000000000000000000000000000000000000000..1658b9a694f3195027ef2b0d77c2164fd760212f
--- /dev/null
+++ b/README
@@ -0,0 +1,33 @@
+# Research Computing OpenOnDemand Message
+
+Note: the rules below are based on [OOD 1.6](https://osc.github.io/ood-documentation/release-1.6/customization.html). We might have to review the rules when we upgrade to newer version of OOD.
+
+In order to track all the announcements we have made, we create this repo to track all the changes. In the repo, there are two files:
+
+- motd
+- announcement.md
+
+### motd
+This will add Message of the Day section in OOD Dashboard.
+In OOD, you can have motd in different format and we have set it to `MOTD_FORMAT="markdown"`. Therefore, you can have markdown syntax in this file.
+
+### announcement
+This will add an announcement message that appears at the top of the OOD Dashboard.
+
+We currently have the file end with `.md` so it will be converted using a markdown converter.
+
+If the announcement file has the extension `yml` and is a yaml file it is first rendered using ERB and then the resulting file is parsed as YAML. The valid keys are:
+| YAML key | Description                                  |Note                                                                     |
+| -------- | -------------------------------------------- | ----------------------------------------------------------------------- |
+|   type   | warning, info, success, or danger            | this is the Bootstrap alert style                                       |
+|   msg    | string containing markdown formatted message | if this is a blank string (only whitespace), the alert will not display |
+
+Because it is rendered via ERB you can do some interesting things, like stop showing the announcement past a specified date:
+```yaml
+type: warning
+msg: |
+  <% if Time.now < Time.new(2018, 9, 24, 12, 0, 0) %>
+  A **Ruby Partial Downtime** for 4 hours on Monday, September 24 from 8:00am to 12:00pm
+  will prevent SSH login to Ruby nodes and and Ruby VDI sessions.
+  <% end %>
+  ```
\ No newline at end of file