On Fri, 27 Aug 1999, Fred L. Drake, Jr. wrote:
It's hard to predict what's needed for good documentation; I am *not* of a mind to avoid having support for very general documentation constructs. We want to have a single DTD to keep the learning curve and tool support under control, so we can't really be too stingy in designing the markup.
I don't think I agree here. Look at POD: it's a wonderful form of documentation for the CPAN modules, and it's a very minimalistic markup. (Of course, it will never be the case that all modules have high quality documentation: we can only solve the technical problems.)
There's more in the library documentation than module sections; this even gets me in trouble sometimes. But it is *very* important to keep in mind that library documentation can and should contain much more than basic reference material.
OK, you're right here. So let me put my original point: A /module/ documentation should have a simple DTD...etc. The library reference should have a more general DTD, which will include a <module> element. Thus we get the best of all worlds: a general documentation format of the sections of the library reference, and a simple format for the every day module documentation. Of course, we'd need <example> and <walk-through> elements, but we'll get to that when we design the DTD.
1. The tutorial is simply a book about Python, and as such should be written like every other technical book. Moreover, Guido is (currently) the sole maintainer so he has last say.
Guido has the last say about everything he does, of course. On the other hand, he's not the only person who maintains the documentation. He's certainly not the one who does the most of the work on it. This makes it sound like a DocBook project.
Of course, that should be re.sub("Guido", "Guido/Fred"), but this doesn't detract from my point: while many people will offer suggestions, having a central maintainer (and a high barrier for entry) is /not/ a bottleneck. I have no problem with that being a DocBook project, especially as I will never have to write anything there<0.5 wink>. Ditto for the next 2 [about the bad Python/C API docs]
The organizational and completeness problems with the API reference are orthagonal to the DTD issue;
Of course: they would have been better as text<wink>. But I do think that part of the problem is organizational, so it's not completely orthogonal to the DTD issue.
we just haven't had the time. I try to add to and enhance the document as specific questions come up, but can't seem to find enough time. (Things should get better once the conversion is done, but not by a whole lot!)
We all appreciate your work, of course.
1. Low barrier for entry: not higher then for writing Python modules.
This is unattainable. The biggest barriers to entry for documentation writing are motivation and natural language. Few people are really good with their own native language, esp. in its written form. Explaining things to others through the written word is very difficult. Python is much easier to learn!
Well, you totally missed me here: of course we can't teach people English nor good style. What I meant was that learning the DTD should be no harder then Python, so just in case we have a super-Python programmer which also won the Pulitzer but doesn't have time to read a 500 page "How to Document in Python for Idiots", he'll be able to write documentation for his modules.
... To call the XML version of the documentation the reference version, I will require an HTML conversion and one typeset version.
Which will probably mean 2python-latex, because that's the easiest way.
A DTD that's too minimal will not be strong enough for writing the documentation. A good DTD that's workable for all the documents is my personal requirement: only one DTD. More than one increases the learning curve for all authors and maintainers.
I disagree: 90% of the authors will only write library reference for their (or other people's) modules. We need, first and foremost, to cater to them. And besides, I do not believe that a single DTD which "does everything" is better then a small set of syncronised DTDs (I definitely do /not/ want to remember that emphasis is <em> in the module docs and <emph> in the tutorial DTD, but we can easily keep that from happening. -- Moshe Zadka <mzadka@geocities.com>. INTERNET: Learn what you know. Share what you don't.