ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Milind Nirgun" <Nirg...@C-IV.org>
Subject RE: My complaint about Ant docs
Date Mon, 12 Aug 2002 19:13:50 GMT
> how it all fits together.  (There are some small code snippets examples
> but, again, they are written for experts.)

I suspect that all the "experts" referred to here have become so reading this same documentation
and using Ant.

> > PS - I've received responses from two people attempting to 
> help me with my problem.  No success from their suggestions, perhaps 
> because their suggestions are as cryptic as the documentation.

Be grateful that someone actually offered to help. In the Evil Empire you would have to pay
for it (and the service would be slower, I am sure).

> > Speaking of pictures...there aren't any.  There are ALWAYS ways of
> > making concepts clearer with illustrations.

BUY A BOOK!! 

-Milind




> -----Original Message-----
> From: Steve Loughran [mailto:steve_l@iseran.com]
> Sent: Monday, August 12, 2002 9:35 AM
> To: Carl Dreher; ant-user
> Subject: Re: My complaint about Ant docs
> 
> 
> 
> ----- Original Message -----
> From: "Carl Dreher" <focusrsh@arn.net>
> To: "Steve Loughran" <steve_l@iseran.com>
> Sent: Monday, August 12, 2002 9:18 AM
> Subject: My complaint about Ant docs
> 
> 
> > > I read the ANT documentation.  (Awful, really, really awful.)
> >
> > Why so? Care to improve it with your own contribution?
> >
> > -steve
> >
> > Well, Ant -is- an open-source project, so any contributions 
> you want to
> > make to improve on our "awful, really, really awful" documentation,
> > please
> > feel free.
> >
> > - Diane
> >
> > =========================
> >
> > Hi,
> >
> > I'm sending this to both of you privately rather than through the
> > mailing reflector because I don't want to start a thread 
> (and subsequent
> > pissing contest) about the state of the documentation.
> 
> actually, I think you should have posted it there, which is 
> why I am sending
> the reply to that group. There are some valid comments, and 
> people new to
> Ant provide feedback on the docs from a different perspective
> 
> I would also point you at Java Development with Ant, by Loughran and
> Hatcher, shipping this week, which at 650 pages has everything from
> beginners to ant experts.
> 
> Likewise, the best part of ant:tdg is that it has some 
> introductory chapters
> on using ant that are fairly readable.
> 
> 
> > I can't get Ant to do even the most basic thing... compile 
> ONE file! So
> > I'm going to rewrite the documentation?  Not a good idea unless,
> > perhaps, you work for the IRS.
> 
> Rewrite? No. But open source projects are built from the voluntary
> contributions of users. Ants docs are lot better than many other OSS
> projects, but we can always do with more.
> 
> (NB: IRS documentation rewrite:
> a) how much money did you earn?
> b) how much have you given us?
> c) give us the rest
> d) if you are late with (c) or lied about (a) or (b), give us 
> some more.
> )
> 
> > My basic complaint is that the documentation is aimed at someone who
> > already is thoroughly familiar with the product.
> 
> agreed
> 
> >Imagine taking an
> > automatic transmission apart (as Dave Barry one said, "down 
> to the very
> > transmission molecules"), throwing all the pieces on a 
> table, taking a
> > picture of it and then declaring that it's been documented. 
>  That might
> > be OK for another transmission specialist but it won't help most
> > mechanics, let alone someone who is unsure of what an automatic
> > transmission is even suppose to do.
> 
> I stick to manual transmissions, me. Clutches are tractable. 
> But I still
> hate those bits in the Haynes manuals where it assumes that 
> you know all the
> basics of the rest of the vehicle: "The clutch is under the 
> big end", or
> skimp on thing they assume is so obvious they dont need to explain how
> "before replacing the thermostat, you must remove the DOHC 
> cam belt" without
> adding caveats like "if you dont put it back right your 
> engine will explode
> messily somewhere down the M4" (**)
> 
> > There is exactly ONE complete example in the docs, in the 
> "Using Ant"
> > section, and it comes long after a bunch of technical 
> definitions that
> > are completely meaningless if you don't first have the big 
> picture of
> > how it all fits together.  (There are some small code 
> snippets examples
> > but, again, they are written for experts.)  I've done a lot 
> of teaching
> > and mentoring in my life and one inviolate rule is that you 
> can NEVER
> > have too many examples, especially at the beginning.
> 
> agreed.
> 
> 
> > What is needed is a "Hello World" type build file that compiles one
> > file. The example should include the source of everything, 
> including the
> > Java files.  Then a Hello World-2 that compiles two file in 
> different
> > directories.  Then a Hello World-3 that compiles a couple 
> of files and
> > includes an outside library.  Etc.  Build slowly with lots of
> > explanations.
> 
> That is a lot of effort. Like enough to fill a book. If 
> anyone wants to do
> it, we welcome it. Having just done it for a book, I am 
> planning on taking a
> rest from those aspects of the documentation, though there 
> are areas that
> still need covering that I may look at. In particular, I am 
> planning on
> adding a better troubleshooting doc from a bit of the book 
> that didnt make
> the final build.
> 
> > By the way, Java Doc is NOT documentation.  It is the 
> equivalent of the
> > transmission picture, referenced above.  Lots of 
> information about the
> > pieces but absolutely no context information or any 
> instructions about
> > how all the pieces fit together.  Furthermore, a Java Doc 
> index is NOT
> > an index at all.  It is really a table of contents.
> 
> um, the ant manual pages are not javadoc, they are a list of 
> tasks with
> examples. The javadocs are separate. Still, I suppose in 
> terms of a factual
> reference the point you are trying to make is the same.
> 
> 
> > Speaking of pictures...there aren't any.  There are ALWAYS ways of
> > making concepts clearer with illustrations.  I find it 
> maddening that,
> > given how incredibly easy it is to make simple drawings and 
> put images
> > in HTML, almost no open-source documentation uses this.
> 
> You have to remember that most of us software engineers are absolutely
> hopeless at illustrations. Unless its a photograph of some mountain
> somewhere, there is nothing I can contribute in that area. If 
> you can...
> 
> >(Interestingly,
> > the Ant documentation I downloaded has an 'images' directory with 36
> > images, all of which appear to be logos, none of which 
> appear anywhere
> > in the documentation.  Huh?)
> 
> We had a competition for logos.
> 
> 
> >
> > Finally (yes, really, finally)...and this is a personal 
> peeve ..if the
> > release says it is **for Windows**, the README (RELEASE NOTES, etc.)
> > files should be in Windows format and NOT Unix format!  I 
> always have to
> > first import those docs into Word and then save them as 
> MSDOS style text
> > documents.
> 
> Maybe we should autogen a readme.txt from readme with file ending
> extensions. Meantime I would like to point you at jEdit 
> (jEdit.org) as an
> excellent open source Java editor with built in support not 
> just for ant,
> but for files with a unix extension. Because we use tools 
> like this we are
> mostly oblivious to line ending details. This is useful when 
> you work in the
> Java world.
> 
> >
> > - Carl Dreher
> >
> > PS - I've received responses from two people attempting to 
> help me with
> > my problem.  No success from their suggestions, perhaps 
> because their
> > suggestions are as cryptic as the documentation.
> 
> Carl,
> 
> The suggestions made sense to me. It is this.
> 
> 1. javac -that is, the real sun javac, not just ant, only 
> autoimports files
> it can find whose directory hierarchy matches its package names.
> 
> You are going
> 
>      <javac srcdir="sql" destdir="${outputDir}">
>        <classpath refid="MyProject.path"/>
>      </javac>
> 
> But there is no reference there to where the utils stuff 
> comes from, and
> even the sql stuff is being handed to javac outside its 
> package hierarchy.
> If you point the compiler at the base of all the source, it will work
> everything out, compiling the utils stuff as needed. Ant's 
> java dependency
> checking also relies on you doing a hierarchy better.
> 
> <target name="compile" depends="prepare">
>      <javac srcdir="src" destdir="${outputDir}">
>        <classpath refid="MyProject.path"/>
>      </javac>
>    </target>
> </project>
> 
> -Steve
> 
> (**) hypothetical example.
> 
> 
> --
> To unsubscribe, e-mail:   
<mailto:ant-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-user-help@jakarta.apache.org>


--
To unsubscribe, e-mail:   <mailto:ant-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-user-help@jakarta.apache.org>


Mime
View raw message