--- a/README.txt	Mon Mar 26 10:41:38 2012 -0700
+++ b/README.txt	Mon Mar 26 11:10:30 2012 -0700
@@ -1,7 +1,23 @@
 configuration
 ===========
 
-multi-level unified configuration
+multi-level unified configuration for python consumption
+
+API
+---
+
+TODO : document this
+
+
+Configuration Files
+-------------------
+
+Config files are useful for (IMHO) A. complicated setup;
+B. reproducibility; C. being able to share run time configurations
+The latter is only useful if the configuration contains nothing
+machine-specific (e.g. the path to an executable might vary from
+machine to machine) or if the configuration is overridable from the
+command line.
 
 ----