diff --git a/.gitignore b/.gitignore
index 807ea25..5bd39a2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
 .Rproj.user
 .Rhistory
 .RData
+_DS_Store
+*.html
diff --git a/README-build-it-up.png b/README-build-it-up.png
new file mode 100644
index 0000000..a79102f
Binary files /dev/null and b/README-build-it-up.png differ
diff --git a/README-set-wd.png b/README-set-wd.png
new file mode 100644
index 0000000..060fef7
Binary files /dev/null and b/README-set-wd.png differ
diff --git a/README.Rmd b/README.Rmd
new file mode 100644
index 0000000..4ca0987
--- /dev/null
+++ b/README.Rmd
@@ -0,0 +1,30 @@
+---
+output: 
+  html_document:
+    keep_md: TRUE
+    variant: markdown_github
+---
+
+dames stands for `d`ata n`ames`. Data names are file names with consistent formatting. Variables are consitently ordered and separated by a consistent separator. Variables are things like date (2015-08-28), abbreviation-or-accronym (AOA), slug-formatted-descriptor (slug-name-of-file-that-describes-its-contents), and file extension (ext).
+
+For example:
+```
+AOA_01_slug-name-of-file-that-describes-its-contents.ext
+```
+
+You set your working directory to clean project directory:
+```{r set-wd, eval = FALSE}
+setwd("path/to/my/project")
+```
+![alt text](README-set-wd.png)
+
+then you can build up your project with `nd`
+```{r build-it-up, eval = FALSE}
+nd("first file")
+nd("another file")
+nd("third file with a different aoa",aoa = "DIFF")
+```
+![alt text](README-build-it-up.png)
+
+Where the output of each op is an damed `.Rmd` file that contains a child link to the REF_template.Rmd (for common stuff) and a YAML header configured for keeping a github-flavoured markdown when knitting to html.
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b819769
--- /dev/null
+++ b/README.md
@@ -0,0 +1,26 @@
+
+dames stands for `d`ata n`ames`. Data names are file names with consistent formatting. Variables are consitently ordered and separated by a consistent separator. Variables are things like date (2015-08-28), abbreviation-or-accronym (AOA), slug-formatted-descriptor (slug-name-of-file-that-describes-its-contents), and file extension (ext).
+
+For example:
+```
+AOA_01_slug-name-of-file-that-describes-its-contents.ext
+```
+
+You set your working directory to clean project directory:
+
+```r
+setwd("path/to/my/project")
+```
+![alt text](README-set-wd.png)
+
+then you can build up your project with `nd`
+
+```r
+nd("first file")
+nd("another file")
+nd("third file with a different aoa",aoa = "DIFF")
+```
+![alt text](README-build-it-up.png)
+
+Where the output of each op is an damed `.Rmd` file that contains a child link to the REF_template.Rmd (for common stuff) and a YAML header configured for keeping a github-flavoured markdown when knitting to html.
+