Documenting
===========

As new capabilities are added to the system, they need to be documented.

As the system evolves, outdated documentation needs to be updated, and 
obsolete documentation needs to be purged.

As the documentation evolves, it needs to be tested to ensure that it is
accurate, useable, adequate, and organized.

The workflow used in this system treats working on documentation as a
programming and testing task, rather than an exercise in writing.  
Developers typically like to program.  Journeymen developers have
used test-driven-devlopment to increase their effectiveness.  The
goal here is to generate adequate to high quality documentation
without getting bogged down with writers block, by relying on 
a developer's skillset. 


New Capabilities
----------------

Whenever you work on a new capability, you are likely to install 
new python packages or other software.  You won't know ahead of 
time what will be needed in the long term, and if so, the exact 
configuration. In addition, these configuration steps will not
be often repeated, so it is easy to forget the exact steps.  
To avoid reinventing the wheel, the work in these configuration 
steps should be captured so that you have the raw material
to document or automate the configuration.

At this time, the recommended practice is to create an .rst
file for the issue.  Run all installation activities from 
a terminal if possible.  Copy the terminal output to the
file, and indent it.   Lead off with a **.. code-block console** 
Sphinx directive.

Auto-Doc Code
-------------

API documentionation is generated using the sphinx.ext.autodoc
extension.  As new modules are written, the initial **package**.rst
file needs to generated.

**Do not use the -f or --force option.** The existing files 
may contain customizations that you don't want to lose.
Instead, if you want to update an existing file, look 
at the file.  If it doesn't contain any customization,
delete the file, and rebuild the documentation.  If it 
does contain customization, rename the file, regenerate
the documentation, and add the customizations back into
the autogenerated file.  Update git as appropriate.

    “A foolish consistency is the hobgoblin of little minds, 
    adored by little statesmen and philosophers and divines. 
    With consistency a great soul has simply nothing to do. 
    He may as well concern himself with his shadow on the wall. 
    Speak what you think now in hard words, and to-morrow 
    speak what to-morrow thinks in hard words again, though 
    it contradict every thing you said to-day. — 'Ah, so you 
    shall be sure to be misunderstood.' — Is it so bad, then, 
    to be misunderstood? Pythagoras was misunderstood, and 
    Socrates, and Jesus, and Luther, and Copernicus, and 
    Galileo, and Newton, and every pure and wise spirit 
    that ever took flesh. To be great is to be misunderstood.”

    -- Ralph Waldo Emerson, 1841 

In general, work on high level API documentation, rather
than focusing on low level docstrings.  With well written
Python code, the interpretion of arguments should be pretty
straightforward.  Strictly applying "complete" docstrings 
with all arguments documented with small functions is likely
to double the size of the code and the effort to maintain it
with perhaps 10 percent additional information useful to 
someone at some time. If some aspect of the code is not
straightforward, consider renaming functions and arguments
rather than elaborating on the docstrings.  

This system relies on Sphinx for documentation.  Consequently,
docstrings can use Restructured Text markup.  Use it to
please the consumer of the API documentation, and have them
think you are a hot-shot rather than clueless.
