= Guiding Principles =

- in general, documentation becomes a lower-class citizen since
  programmers, QA, etc. generally know the system well so will devote
  a minimum of time to writing and maintaining documentation. (In
  addition, usually people solidly familiar with a product are not
  necessarily the best at presenting the product in a way not
  intelligible to experts.)

- documentation is only an issue when it is wrong or when someone new
  to the project spends an inordinate amount of time "getting" the
  software. Experts are (competitively) assumed to be able to
  correctly discern how the system works.

- so, if (good) documentation is desirable, it must be easy for
  programmers to edit the documentation

- everyone wants to edit documentation in their own way.  people will
  avoid editing documentation if it is not easy for them personally

- if documentation becomes a first class citizen and is maintained in
  a repository with the code, documentation changes can be seen in the
  same commit as code changes.  This not only gives a way of seeing
  the project evolve in natural language[*], but also encourages the
  writing of documentation as part of the duty of making a changeset

- DRY


= Overall strategy =

- Each package should have a README.txt in some markdown language

- These README should be read in the appropriate setup.py as the
  `long_description` (e.g.):

"""
try:
    here = os.path.dirname(os.path.abspath(__file__))
    description = file(os.path.join(here, 'README.txt')).read()
except OSError:
    description = ''
"""

   This way, the full descriptions can live with the packages on pypi.

- to note: restructured text (ReST), given a magical flag in setup.py
  that I can never remember, will be rendered on pypi. To the best of
  my knowledge, markdown (the format) cannot be rendered there.  If
  its not restructured text, it will be rendered in text/plain in a
  <pre> so not a big deal

- a script should be written that renders the README.txt files -> HTML
  and posts each to an appropriate place on wiki.m.o or dev.m.o. The
  script will need user auth, which I'm not sure how it is done on
  either side, though we could steal cookies from firefox

- If we need multiple pages, these could live in a docs directory.  Or
  they could just live directly on a wiki.  I'm inclined to keep as
  much as possible with the source if it is at all of interest to
  users and developers.  IMHO, this makes it more likely to be
  maintained and if anyone is operating without internet access or is
  unaware of where to find the documentation on the wiki (always an
  issue for me, anyway), then they will have a local copy on checkout
  (and if they're not using a VCS checkout....maybe they should
  be.  So many python and system packages problems are avoided by
  using virtualenv + setup_development.py -- I have never had a
  problem with these in combination. </digression>).

- In this way, the documentation is available at four entry points --
  {wiki,dev} github, pypi, and with the source on checkout -- but
  since they are mirrored from one canonical source, all documentation
  remains up to date

- since rendered documentation will only be populated via a script (presumedly
  when a new version is in vogue), we control when the documentation
  is "released" to this mirror

- In addition, arbitrary {dev,wiki} pages may be created that do
  not use this strategy.  Only a set of scripts is uploaded to e.g. dev.m.o

- if we ever change our documentation strategy, since there are
  multiple good copies and (unlike sphinx) the script is a glue layer
  rather than a proscription of how to write documentation, we can
  transparently pick a copy and go with it

- diagrams should be done in some sort of declarative syntax versus
  rendered raster images.  For instance, I like graphviz (see
  http://graphviz.org/Gallery.php, or
  e.g. http://k0s.org/portfolio/microfic.gv.txt vs
  http://k0s.org/portfolio/microfic.gv.txt?format=raw ). We could also
  do SVG, but I find SVG to be less declarative and editable for this
  purpose (though of course the resulting rendering can be SVG). This
  has the advantage that diffs to the diagram are human-readable and,
  more importantly, if a diagram needs to be updated then it can be vs
  raster images and the usual need to recreate from scratch.

- culture may encourage documentation contibution.
  I'm a busy person -- we all are -- and often I've
  written very detailed and highly technical documentation on the
  mailing lists only to have to repeat myself several times and
  then be told that I should add it to the (badly
  maintained) wiki documentation In
  short, there is not enough manpower/time to foster a system of
  disincentives.  This means we need to document(!) how to contribute
  and make it very clear that better documentation is the
  responsibility of everyone.  In the same way, if you *see* something
  on a mozmill-dev thread that belongs in the documentation, please
  update; conversely, if you update the documentation in before
  answering a mozmill-dev email, note that too.

- inclusion of source code via identifiers:  there are several pieces
  of software that are able to extract e.g. a function or class from a
  source code file.  We should build upon this to encapsulate
  up-to-date examples in our scripts vs copy+paste.

- leverage of docstrings and comments: one of the best places you can
  document highly technical things is directly in a `.py` or `.js`
  file.  This way, the programmer has the information at their
  fingertips as they program.  Similar to the above, some (though
  probably not all) of these could be included into our docs in an
  (again) non copy+paste manner

----

[*] for extra credit, one could imagine an etherpad-like playback
webpage that shows the evolution of the documentation with links to
the corresponding changeset.

[**] there was a time when if I was semi-interested in a piece of
software I became very non-interested if I saw it was using sphinx.
The README.txt pointed to the index.txt in docs, which had a make file
and some other nonsense, unrendered and generally unreadable
in-source, existing only as a crappy replacement to HTML which, when
you found the website on which it was rendered, was usually mostly
bereft of content anyway