diff --git a/README.md b/README.md
index 1f01dd16..9ba88a1b 100644
--- a/README.md
+++ b/README.md
@@ -48,14 +48,6 @@ For the nice looking powerline symbols to appear, you will need to install a pat
 
 Finally, enable them in vim-airline by adding `let g:airline_powerline_fonts = 1` to your vimrc.
 
-# Bugs
-
-If you encounter a bug, please do the following:
-
-*  reproduce it with this [minivimrc][g] repository to rule out any configuration conflicts.
-*  specify your version and patch level, as well as operating system (found with `:version`).
-*  a link to a gist or your vimrc where it can be reproduced.
-
 # FAQ
 
 Solutions to common problems can be found in the [Wiki](https://github.com/bling/vim-airline/wiki/FAQ).
@@ -64,6 +56,14 @@ Solutions to common problems can be found in the [Wiki](https://github.com/bling
 
 A full list of screenshots can be found in the [Wiki][n].
 
+# Bugs
+
+Tracking down bugs can take a very long time due to different configurations, versions, and operating systems.  To ensure a timely response, please help me out by doing the following:
+
+*  reproduce it with this [minivimrc][g] repository to rule out any configuration conflicts.
+*  include your version of vim, including patches, and operating system (`:version` will contain this information).
+*  a link to your vimrc or a gist which shows how you configured the plugin(s)
+
 # Contributions
 
 Contributions and pull requests are welcome.  Please take note of the following guidelines:
diff --git a/autoload/airline/themes.vim b/autoload/airline/themes.vim
index 6bd5ce0a..18d386de 100644
--- a/autoload/airline/themes.vim
+++ b/autoload/airline/themes.vim
@@ -1,4 +1,4 @@
-" generates a hashtable which defines the colors for each highlight group
+" generates a dictionary which defines the colors for each highlight group
 function! airline#themes#generate_color_map(section1, section2, section3, file)
   "                         guifg           guibg           ctermfg         ctermbg         gui/term
   return {
diff --git a/autoload/airline/themes/dark.vim b/autoload/airline/themes/dark.vim
index ce1e7a7a..635c0d52 100644
--- a/autoload/airline/themes/dark.vim
+++ b/autoload/airline/themes/dark.vim
@@ -1,8 +1,39 @@
+" Each theme is contained in its own file and declares variables scoped to the file.
+" These variables represent the possible "modes" that airline can detect.  The mode
+" is the return value of mode(), which gets converted to a readable string.  The
+" following is a list currently supported modes: normal, insert, replace, visual,
+" and inactive.
+"
+" Each mode can also have overrides.  These are small changes to the mode that don't
+" require a completely different look.  "modified" and "paste" are two such supported
+" overrides.  These are simply suffixed to the major mode, separated by an underscore.
+" For example, "normal_modified" would be normal mode where the current buffer is
+" modified.
+"
+" The theming algorithm is a 2-pass system where the mode will draw over all parts of
+" the statusline, and then the override is applied after.  This means it is possible
+" to specify a subset of the theme in overrides, as it will simply overwrite the
+" previous colors.
+
+" First let's define some arrays.  The s: is just a VimL thing for scoping the
+" variables to the current script.  Without this, these variables would be declared
+" globally.  The array is in the format [ guifg, guibg, ctermfg, ctermbg, opts ].
+" The opts takes in values from ":help attr-list".
 let s:file = [ '#ff0000' , '#1c1c1c' , 160 , 233 , '' ]
 let s:N1 = [ '#00005f' , '#dfff00' , 17  , 190 ]
 let s:N2 = [ '#ffffff' , '#444444' , 255 , 238 ]
 let s:N3 = [ '#9cffd3' , '#202020' , 85  , 234 ]
+
+" vim-airline is made up of multiple sections, but for theming purposes there is
+" only 3 sections: the mode, the branch indicator, and the gutter (which then get
+" mirrored on the right side).  generate_color_map is a helper function which
+" generates a dictionary which declares the full colorscheme for the statusline.
+" See the source code of "autoload/airline/themes.vim" for the full set of keys
+" available for theming.
 let g:airline#themes#dark#normal = airline#themes#generate_color_map(s:N1, s:N2, s:N3, s:file)
+
+" Here we define overrides for when the buffer is modified.  This will be applied
+" after g:airline#themes#dark#normal, hence why only certain keys are declared.
 let g:airline#themes#dark#normal_modified = {
       \ 'info_separator': [ '#444444' , '#5f005f' , 238     , 53      , ''     ] ,
       \ 'statusline':     [ '#ffffff' , '#5f005f' , 255     , 53      , ''     ] ,
diff --git a/doc/airline.txt b/doc/airline.txt
index 8d364f57..f8e1b00e 100644
--- a/doc/airline.txt
+++ b/doc/airline.txt
@@ -182,6 +182,14 @@ example that you could add to your vimrc:
   call add(g:airline_window_override_funcrefs, function('MyPlugin'))
 <
 
+==============================================================================
+WRITING THEMES                                              *airline-themes*
+
+Themes are written "close to the metal" -- you will need to know some basic
+VimL syntax to write a theme, but if you're written in any programming
+language it will be easy to pick up.  Have a look at the dark.vim theme
+where it is fully documented.
+
 ==============================================================================
 TROUBLESHOOTING                                    *airline-troubleshooting*