diff --git a/README.md b/README.md
index 31262c9..43a1037 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,23 @@ and initialize the various submodules (mostly Vim plugins).
 
 Enjoy.
 
+## Shell Environment
+
+As much as possible, I tried to keep these files as system agnostic as
+possible. I work on lots of different systems so having the ability to bring
+down my core environment and customize it is very useful. Most of the
+environment files have three levels:
+
+1. The main file (e.g. `.zshrc`).
+2. A system specific file whose name is generated by the `uname -s` command.
+   So, these files have names like `.zshrc.darwin` and `.env.linux`. The system
+   name is exported as `$SYS` in the `.env` script.
+3. A machine specific file whose name is derived by appending `.local` to the
+   main file's name (e.g. `.zshrc.local`).
+
+Files 2 and 3 are sourced at the end of the main file, so any settings you add
+there will override those set in the main file.
+
 ## License
 
 Everything in this repository is licensed under the [Creative Commons