xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Ted Leung" <twle...@sauria.com>
Subject Documentation Format Proposal
Date Tue, 10 Apr 2001 17:49:42 GMT
Let me provide a bit of history here.

The decision to use Stylebook was made at the creation of the project
under the assumption that we would switch to Cocoon2 when Cocoon2
was completed.   At that time, we believed that Cocoon2 was to be finished
quite soon.    The original plan was to be able to generate both the
web-site
and the documentation using a single tool.

Well, time goes by, and here we are, with a cobbled together system atop
a tool that is barely maintained.  So it seems to me that it's time to do
something
about it.

At ApacheCon, I spoke with one or two people about the practicality of our
original
plan.  I've been told that Cocoon2 is going to ship in the next month or so.
If this is
the case, I'd like to see us switch the website and docs over to Cocoon2.
Cocoon
is one of our projects, and if possible, I'd like to see us use it.  But, we
also have
some real needs to improve both our web-site and our documentation.

So here's my proposal:

1) someone from the Cocoon2 community tell us if Cocoon2 will be done soon
2) if it will be, then let's get any interested parties working on Cocoon2
logicsheets
that do the job
3) lets get more volunteers to modify the various projects' websites to use
Cocoon2.
4) if Cocoon2 is not going to be ready in some reasonable timeframe (a month
or  two),
we start looking for a standardized alternative (DocBook has been mentioned)

Ted

----- Original Message -----
From: "Kelly Campbell" <camk@channelpoint.com>
To: <general@xml.apache.org>
Sent: Thursday, April 05, 2001 4:44 PM
Subject: RE: Documentation Format (was Re: Help wanted: more qualified
developers)


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


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