xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From giacomo <giac...@apache.org>
Subject Re: Documentation Format Proposal
Date Tue, 10 Apr 2001 20:44:22 GMT


On Tue, 10 Apr 2001, Ted Leung wrote:

> 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

The plan is to go beta around May 1st.

> 2) if it will be, then let's get any interested parties working on Cocoon2
> logicsheets
> that do the job

What logicsheet do you have in mind (I ask because I don't see any need
for them)?

> 3) lets get more volunteers to modify the various projects' websites to use
> Cocoon2.

When we get the content aggregation finished this month we'll be able to
use our existing xdocs (written in the DTDs Stefano had developped
almost years ago) directly as we have done with Stylebook and use
Cocoon2 to produce the web site as well as the documentation in
different flawors of HTML or PDF.

I'd like to have volunteer starting to try out Cocoon2 to produce the
static web site and docs. At the moment most of the active developpers
are working hard on finilizing the Cocoon 2 features (and thus docs
seems not to have importance :/ ) but I'm sure that any help those
volunteers need can be pulled off from the cocoon-dev lists.

Giacomo

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


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