[Doc-SIG] On David Ascher's Rant

[uche.ogbuji@fourthought.com]

David,

I confess I don't quite get it, which is too bad because I respect your 
opinions and would like to know precisely what you're getting at.

Maybe the problem is that I'm a doc-sig newbie.  I just showed up here a 
couple of weeks ago to mention that we had a few internal tools at FourThought 
for python documentation and I wondered if anyone was interested.

As such, I don't have any sense that the doc-sig has or is failing in any way. 
 The way I see it, Python has a decent amount and quality of documentation.  
True it is not as good as Java's or Perl's but it is about as much as can be 
expected given its age and market profile.  Fred Drake has done a phenomenal 
job.  My understanding is that we're all discussing a way to push it to the 
next level.  If possible, it means leap-frogging Perl and Java, but mostly it 
just means seeking the best solution.  I don't see any need for haste or panic.

I don't understand the reasoning that python docs should look like Python.  
I'm not as familiar with POD, but you also give Javadoc as an example, and it 
looks _nothing_ like Java.  Also note that several people have been advocating 
a Javadoc-like system, including myself.  So where is the terrible divergence?

XML advocates here are mostly suggesting it for the "library" format of python 
documentation, not the "author" format.  So why does it matter if you think 
authors bear such distaste for XML and TeX?  They won't have to deal with it.  
The reality, though, is that it's easier to go from XML or TeX to any of the 
many formats Python users want than it would be from Jim-Fulton-David-Ascher 
pythonic documentation format.  Would you volunteer to write the tools to go 
from JFDA to *roff for man pages, postscript, PDF, HTML and GNU info?  I doubt 
it, and even if you would, I'd advise against re-inventing the wheel that the 
Linux Documentation Project has so admirably crafted.

The way I see it, your key argument with Manuel's proposals would be that he 
plans to inflict TeX on Python authors.  I agree that that is a bad thing, and 
I also wouldn't want to inflict XML on Python Authors.  I don't think that's 
an alien sentiment here, but your rant makes it sound that way.

So, what am I missing?


-- 
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