--- trunk/OOPSE/libmdtools/DumpWriter.cpp	2004/01/13 20:35:25	936
+++ trunk/OOPSE/libmdtools/DumpWriter.cpp	2004/01/15 14:22:16	947
@@ -171,6 +171,43 @@ void DumpWriter::writeFrame( vector<ofstream*>& outFil
 
 #ifdef IS_MPI
   
+  /*********************************************************************
+   * Documentation?  You want DOCUMENTATION?
+   * 
+   * Why all the potatoes below?  
+   *
+   * To make a long story short, the original version of DumpWriter
+   * worked in the most inefficient way possible.  Node 0 would 
+   * poke each of the node for an individual atom's formatted data 
+   * as node 0 worked its way down the global index. This was particularly 
+   * inefficient since the method blocked all processors at every atom 
+   * (and did it twice!).
+   *
+   * An intermediate version of DumpWriter could be described from Node
+   * zero's perspective as follows:
+   * 
+   *  1) Have 100 of your friends stand in a circle.
+   *  2) When you say go, have all of them start tossing potatoes at
+   *     you (one at a time).
+   *  3) Catch the potatoes.
+   *
+   * It was an improvement, but MPI has buffers and caches that could 
+   * best be described in this analogy as "potato nets", so there's no 
+   * need to block the processors atom-by-atom.
+   * 
+   * This new and improved DumpWriter works in an even more efficient 
+   * way:
+   * 
+   *  1) Have 100 of your friend stand in a circle.
+   *  2) When you say go, have them start tossing 5-pound bags of 
+   *     potatoes at you.
+   *  3) Once you've caught a friend's bag of potatoes,
+   *     toss them a spud to let them know they can toss another bag.
+   *
+   * How's THAT for documentation?
+   *
+   *********************************************************************/
+
   int *potatoes;
   int myPotato;