M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1)

[Fred L. Drake, Jr.]

Moshe Zadka wrote:
 > Assumption 1:
 > 	doc-strings should be flexible enough to document most Python
 > 	modules without any OOL documentation (that is, as I understand,
 > 	our majority vote). The "most" comes because it shouldn't

Peter Funk writes:
 > I see:  IMHO this first assumption is wrong.  Good reference
 > documentation often requires complex material like tables, figures,
 > formulas and more text, which will clutter up the source and distract

  Ok, guys, I think this points out where the communications failure
is (what other kind is there?).
  Docstrings, combined with language information obtained from the
parse tree or reflection, should be sufficient to generate "usable"
documentation "most" of the time.
  Note that "usable" and "most" are fairly vague; don't assume they're 
tightly related to "optimal" or "all".
  "Usable" means that names of classes, functions, and parameters are
available and can be presented reasonably, and the docstrings can be
used to augment the information content with descriptions and
examples.
  As for "most", I'd be quite happy to hit 75% to 80% of modules at
the "usable" level.

 > It should be possible to autogenerate *some* kind of reference
 > documentation from doc-strings during early stages of the lifetime
 > of software.  Later, when the software becomes more mature and
 > complex, it should be possible to use this autogenerated material
 > as a starting point for more elaborate documentation.  So not all
 > features, which would be available at the higher XML level and
 > which you see used in the current python library reference need to
 > have a counterpart in an upcoming doc-string grammar.

  Agreed.
  I think David Ascher and the structured-text proponents are likely
to come up with a very reasonable proposal.  For modules which require 
more structure or author-control of semantic labelling than we can
extract from the module source (docstrings + (parse tree or
reflection)), it's perfectly reasonable to say "You need to use the
heavy stuff."
  (Moshe:  Please don't think I meant that *you* really had to do
*everything* with the documentation!  I was just joking about that at
the IPC8 Doc-SIG session!  We welcome your participation, but it's up
to me to act as channel for the BDFL here; keeps the hate mail in my
box rather than yours. ;)


  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives