ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David A. Bartmess" <>
Subject Re: Improving the manual
Date Thu, 28 Jul 2005 00:21:24 GMT
I would be willing to help, since even being a somewhat-seasoned 
(garlic anyone?) Ant developer, I STILL have problems reading the 
manual and getting info on what I need it to DO, not what the parameters are!

At 11:18 AM 7/27/2005, you wrote:
>The big problem with the Ant manual is the people who wrote it knew 
>too much. I can see various ways to make it more intelligible to the 
>first timer:
>1. define a term like project or target the first time it is 
>used.  Don't even presume people know what MAKE is.  Ant should be 
>accessible to people building their first jar.
>2. start off with a glossary of terms.  When writing this, suppress 
>the urge to impress or explain the full abstract 
>generality.  Explain not so much what something does as what it is FOR.
>3. In the introductory examples, be specific about precisely where 
>things are. Don't say in ${src}, be extremely specific. Say in 
>c:\com\mindprod\myproject\src.  If the specificity of Windows 
>bothers you, be specific about a UNIX example. Keep in mind your 
>readers don't understand Ant yet. You can't presume they understand 
>the way it combines directories.  My biggest initial problems with 
>ant came from trying to understand where it was looking for and putting things.
>4. Give recipes.  Most people don't want to understand Ant, at least 
>at first. They just want to get the job done.  How about a set of 
>graded recipes -- totally canned scripts ready to go, just change 
>the name of your projects and Main classes. Set your project up this 
>way and a even a rank novice can use ant without thinking to get jars built.
>a) Simple: one main class with Genjar
>b) With two resources: e.g. a *.ser file and a *.png.:
>c) With dynamic classes: a wildcard tree from some other project.
>d) With a meta-ant script: to run all the individual ant scripts
>These recipes allow you to explain best practices. An example is 20 
>times clearer than the best prose.
>5. ask experienced users to submit a library of scripts from the 
>real world, heavily commented about what they are intending to do 
>and how they are doing it.
>I am willing to write, but I would need someone to correct my work, 
>since much of Ant is still a mystery to me.
>Canadian Mind Products
>#327 - 964 Heywood Avenue
>Victoria, BC CANADA V8V 2Y5
>roedy green                (250) 361-9093 emergency
>To unsubscribe, e-mail:
>For additional commands, e-mail:

David A. Bartmess
Software Configuration Manager
jSyncManager Open Source PDA Sync Program

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message