xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kelly Campbell <c...@channelpoint.com>
Subject RE: Documentation Format (was Re: Help wanted: more qualified de velopers)
Date Thu, 05 Apr 2001 23:44:37 GMT
Marin,

I don't think anyone is advocating changing the documentation to only one
output format. I think we want to demonstrate the usefullness of XML in
producing multiple formats from one source, while at the same time
exercising our various "products" like Xerces, Xalan, FOP, etc. 

Documentation is one key area that people are requesting more action on
which lends itself well to multiple formats from one source. The typical
formats desired are plain text, html, and printable pages, all of which we
can do, and in fact, many of us already do daily. Other formats include more
topic-oriented systems like online help, javadocs, etc. IBM has tried to
address some of these disparate requirements with their DITA initiative:
http://www-106.ibm.com/developerworks/xml/library/x-dita1/index.html

I think the debate is "what is the format of that one source?"

I definitely agree with your "keep the entry barrier low" argument, and this
is why I would prefer docbook because it is so well documented and somewhat
standardized. The arguments on docbook easily go the other way too. Some
people consider it too complex and hard to learn. I think anything that has
an O'Reilly book at my local bookstore can't be all that hard to learn :-)

I was just hoping that some of the people here who know stylebook better
than I do (I admit to barely knowing it at all) could explain why we might
prefer to stay with it instead.

For those of you who might be more interested in the topic of XML and
documentation, I would recommend checking out the xml-doc mailing list at
yahoogroups. They've had this same debate over what dtd's and schemas are
good for what reasons many times over.

-Kelly


> -----Original Message-----
> From: Martin Stricker [mailto:shugal@gmx.de]
> Sent: Thursday, April 05, 2001 5:21 PM

> Please keep the documentation format as simple as possible! I 
> want to be
> able to read it on a linux console (text only, no graphical user
> interface).
> 
> BTW: The higher the learning curve for writing xml.apache.org
> documentation is the lower is the chance I'll write some...
> 
> 

---------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org


Mime
View raw message