--- a/doc/v2_planning/API_coding_style.txt	Thu Sep 16 16:12:02 2010 -0400
+++ b/doc/v2_planning/API_coding_style.txt	Thu Sep 16 16:24:47 2010 -0400
@@ -38,9 +38,12 @@
       <http://www.python.org/dev/peps/pep-0008>`_
     * `PEP 257 -- Docstring Conventions
       <http://www.python.org/dev/peps/pep-0257>`_
+    * `Numpy Docstring Standard
+      <http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines#docstring-standard>`_
     * `Google Python Style Guide
       <http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>`_
 
+
 However, there are a few points mentioned in those documents that we decided
 to do differently:
 
@@ -107,3 +110,50 @@
                                            my_everything]:
             ...
 
+The ``logging`` Module vs. the ``warning`` Module
+=================================================
+
+The ``logging`` Module
+----------------------
+
+A central logging facility for Python capable of logging messages of various
+categories/urgency and choosing with some granularity which messages are
+displayed/suppressed, as well as where they are displayed or written. This
+includes an ``INFO`` level for innocuous status information, a ``WARNING`` level
+for unexpected state that is still recoverable, ``DEBUG`` for detailed
+information which is only really of interest when things are going wrong, etc.
+
+In addition to the `library documentation`_, see this helpful tutorial,
+`Python Logging 101`_.
+
+.. _library documentation: http://docs.python.org/library/logging.html
+.. _Python Logging 101: http://plumberjack.blogspot.com/2009/09/python-logging-101.html
+
+The ``warning`` Module
+----------------------
+
+The ``warning`` module in the standard library and its main interface, the
+``warn()`` function, allows the programmer to issue warnings in situations where
+they wish to alert the user to some condition, but the situation is not
+urgent enough to throw an exception. By default, a warning issued at a given
+line of the code will only be displayed the first time that line is executed.
+By default, warnings are written to ``sys.stderr`` but the ``warning`` module
+contains flexible facilities for altering the defaults, redirecting, etc.
+
+Which? When?
+------------
+
+It is our feeling that the ``logging`` module's ``WARNING`` level be used to log
+warnings more meant for *internal*, *developer* consumption, to log situations
+where something unexpected happened that may be indicative of a problem but
+is several layers of abstraction below what a user of the library would
+care about.
+
+By contrast, the warning module should be used for warnings intended for user
+consumption, e.g. alerting them that their version of Pylearn is older than
+this plugin requires, so things may not work as expected, or that a given
+function/class/method is slated for deprecation in a coming release (early
+in the library's lifetime, ``DeprecationWarning`` will likely be the most common
+case). The warning message issued through this facility should avoid
+referring to Pylearn internals.
+