You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@xml.apache.org by Kelly Campbell <ca...@channelpoint.com> on 2001/04/06 01:44:37 UTC
RE: Documentation Format (was Re: Help wanted: more qualified de
velopers)
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
Re: Documentation Format Proposal
Posted by giacomo <gi...@apache.org>.
On Wed, 11 Apr 2001, Ted Leung wrote:
>
> ----- Original Message -----
> From: "giacomo" <gi...@apache.org>
> To: <ge...@xml.apache.org>
> Sent: Tuesday, April 10, 2001 1:44 PM
> Subject: Re: Documentation Format Proposal
>
>
> >
> > On Tue, 10 Apr 2001, Ted Leung wrote:
> >
> > >
> > > 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.
>
> Sounds close to me
>
> > > 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)?
>
> If we only need stylesheets, that's fine by me.
>
> > > 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.
>
> So we won't have to change the docs from stylebook format?
I think for a first round we can leave the doc format as it is today.
Giacomo
>
> > 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
>
>
>
> ---------------------------------------------------------------------
> 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
Re: Documentation Format Proposal
Posted by Ted Leung <tw...@sauria.com>.
----- Original Message -----
From: "giacomo" <gi...@apache.org>
To: <ge...@xml.apache.org>
Sent: Tuesday, April 10, 2001 1:44 PM
Subject: Re: Documentation Format Proposal
>
> On Tue, 10 Apr 2001, Ted Leung wrote:
>
> >
> > 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.
Sounds close to me
> > 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)?
If we only need stylesheets, that's fine by me.
> > 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.
So we won't have to change the docs from stylebook format?
> 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
---------------------------------------------------------------------
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
Re: Documentation Format Proposal
Posted by giacomo <gi...@apache.org>.
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" <ca...@channelpoint.com>
> To: <ge...@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
Documentation Format Proposal
Posted by Ted Leung <tw...@sauria.com>.
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" <ca...@channelpoint.com>
To: <ge...@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