further documentation progress.  ironically, the more I document, the more I want to go back and add to the code.  It looks like this will take a few iterations more