[Doc-SIG] Approaches to structuring module documentation

[Fred L. Drake, Jr.]

Moshe Zadka writes:
 > Hmmmmm....define User's Manual. What do you want from it?

  How to work with the interpreter and related tools.  It wouldn't
teach the language, but would teach the environment and provide
reference material for things like the user interface (for PythonWin
or IDLE, or readline information for Unix).  Debuggers and profilers
generally fall into this category of information.

 > Again, it is a "real" problem, not an artifact of the solution: either you
 > have AI, or you patiently tell the computer what every word means, or you
 > live in a non-perfect world. Most solutions are a combination of all three
 > approaches: use a bit of smart in the processor, put some markup, and live
 > with the fact that some information will require a human to discover ;-)

  I agree.  I think we have too little useful markup now.

 > It doesn't matter: you'd still have to use the micro-document approach
 > for this to work. I just painted a rosy picture of what it would buy you.

  No, you can still use a non-microdocument architecture.  I failed to 
present the mega-database-dump model for a reason, though.  ;-)  It's
entirely possible to use the sort of markup I presented in my sample
module reference without using micro-documents.  It just gets very
painful.

 > But I can live with straight XML, if that's the party line.

  I don't think there's a "party line"; I just want to avoid
introducing new dialects and processing stages.  There's enough that
really needs doing on the content side of things that we don't need to 
create new problems.


  -Fred

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