[Doc-SIG] Approaches to structuring module documentation

[Paul Prescod]

Sorry for the delay on this message. I need a long plane flight to be
able to think about this issue properly.

"Fred L. Drake, Jr." wrote:
> 
>   Well, now that things have quieted down a little (where?!), I'll
> stir things up a little.
>   Two broad approaches to structuring the documentation have been
> presented:  One is the current document-centric model, where there are
> a number of books/manuals/whatever that contain interesting
> information, but need to be used as really large chunks.  Extracting
> specific information is (appearantly) difficult for humans (witness
> the recent request for a random() function on the newsgroup by someone
> who said they looked in the index; just the wrong one); 

I'm preaching to the choir when I say that there are three issues here:

 * content
 * structure of the content
 * presentation

Okay, they are all related but they are still different. If somebody
can't find something, I would tend to try to fix that in the
presentation first, and then in the content and finally in the structure
if all else fails. Let's not jump right to the structure. Consider this
analogy: someone using a word processor cannot figure out how to bold
something so we decide to change the file format? Sure, there is a small
chance that the file format is to blame (e.g. it doesn't support bold!)
but it is much more likely just a UI problem.

Also, consider our choices a graph with two axes:

 * specificity of markup
 * granularity ("library", "package", "module", "class) of file

If you think of it that way, then you realize that you could have a very
generic microdocument architecture (one HTML class per symbol) or a very
specific (PyBook) but ungranular (the WHOLE book) DTD. And of course the
other two options are also availble.

>   This approach has the advantage of matching the current structure of
> the documentation.  The conversion isn't terribly difficult or even
> time consuming given the state of the things in Doc/tools/sgmlconv/ in
> the CVS repository.  There's clearly some work to do regarding DTD
> specification and probably a bit of transformation, but a large part
> of the coding and testing is done.

I believe that this advantage strongly overwhelms any benefits of going
to a more theoretically pure markup. It's taken roughly a year to get
our documents clean enough that they can even move to XML or something
similar. How long would it take to completely reorganize them? You,
Fred, have a job that only partially includes documentation maintenance
and the rest of us are not nearly so interested in re-writing DOCS as we
are in re-writing CODE. I fear that a move to Microdocuments would never
happen.

>   This explosion of markup is of most concern for authors; a lot of
> markup is required to encode enough information to justify changing
> the approach.  As more markup is required, it is increasingly
> difficult to get contributions because it takes the authors more time
> to document their work.  I'd like to maintain Python's standing as the
> best-documented free scripting language, and I'm not sure authors will
> be willing to use the more extensive markup.

That's a killer argument.

>   The hybrid approach can be considered as roughly the same as the
> microdocument approach, as discussed above.

I propose an incremental approach. Let's get to PyBook XML and THEN
re-evaluate PyBook in terms of microdocument. 

Here's an important issue: Perl and Java have achieved a relatively high
level of module documentation conformity by putting the microdocument
*in the code*. This appeals strongly to basic human nature. One file
instead of two. Scroll to the top to fix up the documentation, and so
forth. Python 2 should address this by having a first-class
documentation feature built into the grammar. I would advise that it
should NOT be XML. In fact it should probably be roughly JavaDOC or
POD-ish so that we aren't reinventing the wheel.

-- 
 Paul Prescod  - ISOGEN Consulting Engineer speaking for himself
Bart: Dad, do I really have to brush my teeth?
Homer: No, but at least wash your mouth out with soda.