ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Roedy Green <roe...@mindprod.com>
Subject Improving the manual
Date Wed, 27 Jul 2005 17:18:14 GMT
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


Mime
View raw message