[Doc-SIG] Documenting Python, Take 2 (RE-POST)

[uche.ogbuji@fourthought.com]

Pardon me if you get this twice, but I had problems with mail at python.org 
yesterday

Sorry it took so long to get around to this.

I think my earlier approach (let's call it a meta-proposal) to settling on a 
Python documentation system still applied, with some modifications.

My original posting is at

http://www.python.org/pipermail/doc-sig/1999-September/000726.html

But in light of the current discussion and concerns that have been raised, 
changes are in order.

Python Documentation Python Meta-Proposal
-----------------------------------------

I think in essence we must quickly decide on a set of documentation formats 
and enabling tools, and then answer the questions of how to get there from 
where we are.  A step-wise transition, as Paul suggests, is fine, but I think 
it is important for us all to have a vision of where we're going.

FORMATS:

F1) A highly-structured format for archiving and manipulation of low-level 
documentation (what Fred Drake is calling "microdocuments").  Example: SGML or 
XML schema.  This format must be semantically complete, easy to manipulate in 
code, with a broad toolset available for manipulation.

F2) An author-friendly format for low-level documentation.  F2 has to be 
structured enough for meaningful conversion to F1, but terse enough for use in 
in-line documentation and adoption by authors for whom F1 would be too much of 
a chore.  Example: javadoc, POD.

F3) An author and maintainer-friendly format for general documentation, such 
as the Python profiler and debugger docs as well as the User guide and all 
that.  Example: Docbook, RTF.  Abundance of author and manipulation tools is 
important for this format.


CUSTOM TOOLS:

T1: A tool for conversion from F1 to F2 and back.

T2: A tool for interactively querying authors for documentation elements: 
basically a knowledge-acquisition tool from python module experts. (Maybe you 
can guess what one of our recent contracts has been).

T3: A tool for generating user-friendly doc-strings into python modules from 
the information in F1.

T4: A command line tool that can display user-friendly docs from a database of 
F1 docs, similar to perldoc.

T5: A tool for turning F1 and F3 into the familiar Python User Guide and 
Library Reference, preferably with richer linking.

T6: A tool for generating man-pages based on F1 Documentation.  This would 
address the insistent crowing of Tom Christiansen about Python's "man-page 
envy"

In a separate message, I'll make a proposal based on this meta-proposal.


-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org