[Doc-SIG] XML Conversion Update

[Moshe Zadka]

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.