--- a/README.txt	Wed Mar 28 09:03:02 2012 -0700
+++ b/README.txt	Wed Mar 28 10:27:17 2012 -0700
@@ -3,10 +3,27 @@
 
 multi-level unified configuration for python consumption
 
+- you have a (python) program that wants to read configuration from
+  configuration files (I currently support JSON and YAML) and also
+  from the command line
+- you want to be able to serialize and deserialize configuration
+
 API
 ---
 
-TODO : document this
+The ``configuration.Configuration`` class implements an abstract base
+class that extends ``optparse.OptionParser``.  The form of the
+configuration is dictated by setting the ``options`` attribute on your
+subclass.  ``options`` is a dictionary of the form::
+
+  {'name': {<value>}}
+
+``name`` is the name of the configuration option, and ``value`` is a
+``dict`` that gives the form of the option.
+
+
+For an example, see
+http://k0s.org/mozilla/hg/configuration/file/c831eb58fb52/tests/example.py#l7
 
 
 Configuration Files