ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David A. Bartmess" <dingod...@edingo.net>
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    roedyg@mindprod.com
>#327 - 964 Heywood Avenue
>Victoria, BC CANADA V8V 2Y5
>http://mindprod.com
>roedy green                (250) 361-9093 emergency
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
>For additional commands, e-mail: user-help@ant.apache.org
>
>
>

---------------------------
David A. Bartmess
Software Configuration Manager
http://edingo.net
---
jSyncManager Open Source PDA Sync Program
Developer
http://jsyncmanager.org



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


Mime
View raw message