ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Brett Knights" <br...@knightsofthenet.com>
Subject RE: script task: suggestion about the docs
Date Thu, 21 Jun 2001 16:05:45 GMT
Notice the "available documentation" clause in my original post.
Regardless of our intentions, what is right, what should be done, or any other consideration:
 - open source projects with complete documentation are an exception rather than a rule.
 - no one is jumping up to say "No more development until the docs are complete"
 - no one is jumping up to say "I'll spend all my free time upgrading the docs"

If there weren't an implicit assumption that people really will be able to read the code if
necessary then new code and complete
documentation would go hand-in-hand. The complaint that started this thread wouldn't have
occurred because the script task wouldn't
have been released without a description of the intended architecture, step-by step examples
in each of the supported languages etc.
being included in the docs.

I, somewhat obviously :-), happen to think that the level of documentation provided with Ant
is excellent and sufficient for use.
I'm certainly not saying the docs are perfect. If the Ant developers want to have it become
a standard tool for use by
non-programmers the documentation will have to be improved and take a much more step-by-step
and tutorial based approach. Time will
tell if they go that route.

BTW Kudos to you if you really learned to use Emacs from the included documentation and didn't
"get off the ground" with it by
learning from someone who had already been there or from a third party text that someone was
paid to write.

> -----Original Message-----
> From: Jesse Tilly [mailto:JTilly@hoteltools.com]
> Sent: Wednesday, June 20, 2001 6:45 AM
> To: 'ant-user@jakarta.apache.org'
> Subject: RE: script task: suggestion about the docs
>
>
> Reading the code is certainly not how I learned to use Emacs
> or GCC...and
> *thank God*!  Documentation is source in itself and should be
> maintained
> with the same regard.  And this goes for in-code
> documentation as well.
> They're all important.
>
> MrT
>
> > -----Original Message-----
> > From: Stefan Bodewig [mailto:bodewig@apache.org]
> > Sent: Wednesday, June 20, 2001 2:27 AM
> > To: ant-user@jakarta.apache.org
> > Subject: Re: script task: suggestion about the docs
> >
> >
> > Brett Knights <brett@knightsofthenet.com> wrote:
> >
> > > It's OPEN SOURCE. It's expected that you WILL read the
> source if you
> > > have questions not answered by the available documentation.
> >
> > Not really, this is what we have documentation, a FAQ and mailing
> > lists for.  Sure, you are going to learn a lot about Ant
> (or any other
> > open source project for that matter) by reading the code.  But we
> > don't expect everybody to do so.
> >
> > Stefan
> >
>


Mime
View raw message