[Doc-SIG] Approaches to structuring module documentation

[Fred L. Drake, Jr.]

Bill Janssen writes:
 > Well, I might as well put in my two cents worth.

  Surely we can ask three or four cents worth from you; we've
certainly not hesitated sending comments to the ILU list at various
times!  ;-)

 > The GNU Info versions of the Python documentation are the most
 > important to me, as I can put those right into my Emacs and have them
 > at the tip of my fingers while programming.  Whatever solution is
 > found, I'd like to see that continued.

  I don't expect there will be any reduction in the set of output
formats.  Which is not to say that info will be the first one
produced, but it's a safe bet it'll stay around.  I suspect it'll be
far easier to maintain if it's no longer dependent on the HTML
rendering of the docs as well.

 > There's some logic to javadoc, I suppose, in that the most common
 > problem with documentation is that it goes out of date, because the
 > modifier just changes the code.  If the documentation is mixed with
 > the code, perhaps that probability is reduced (though I'm not aware of
 > any studies that show this to be true).  Though something like

  I think I've seen references to studies that showed it both ways, so 
I suspect that the specific set of programmers studied remains a
poorly understood variable (hey, we're not numbers, we're variables!).
  I hope that a moderate amount of what gets marked up in JavaDoc
comments would be generated automatically for Python, but I suspect
that will be very difficult and prone to be wrong if people make heavy 
use of Python's dynamic features.  But that's the case now as well,
and screwing with the standard library is a de-facto no-no.

 > Literate Programming might be a better system.  Perhaps adapting a
 > system like Noweb (http://www.eecs.harvard.edu/~nr/noweb/) would be of
 > help.  The home page lists a number of programming languages, but not
 > Python.

  Now John Skaller will probably suggest that we all adopt
Interscript.  ;-)
  I'm not entirely sure what we'd expect to get out of a literate
programming system that we can't get out of a JavaDoc/POD/Structured-
Text-derived system, at least as far as module reference material
goes.  I've not done enough literate programming to be a good judge of 
how well it really works for library code.  I'd love it if someone
would send me a pointer to a really nice example of literate
programming of a library that provided reference documentation,
introductory material, and examples of use.  (Esp. if there's both
online and typeset versions of the documentation to look at.)
  I would *not* expect this to be applied to the Python libraries,
however, since there are too many hands in there to get a major shift
in methodology.  Just getting decent docstrings will be hard enough
some days!


  -Fred

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