diff --git a/MODES b/MODES
new file mode 100644
index 0000000..01cc3ca
--- /dev/null
+++ b/MODES
@@ -0,0 +1,26 @@
+This document is designed to be a quick (and incomplete) description of how
+modes work, how you might create one yourself, etc.
+
+1. What are modes?
+
+Pmacs uses modes to determine what actions can be applied to a buffer, which
+keys should apply which actions, how the buffer should be highlighted, how the
+buffer should be indented, and any other per-buffer configuration. The default
+mode ("Fundamental") provides the base functionality which all other modes
+inherit.
+
+All modes are loaded and installed in application.py. It would be nice if there
+was a configuration file where you could add your own modes, but there isn't.
+Loading a module involves the following:
+
+    # mandatory; modename should be lowercase
+    self.modes[modename] = package.ModeClass
+
+    # specify full paths which should use this mode
+    self.mode_paths['/some/full/path'] = 'modename'
+    # specify filenames (i.e. .bashrc) which should use this mode
+    self.mode_basenames['filename'] = 'modename'
+    # specify file extensions (i.e. .txt) which should use this mode
+    self.mode_extensions['.junk'] = 'modename'
+    # specify executable name in comment (i.e. bash from #!/usr/bin/bash)
+    self.mode_detection['junk'] = 'modename'