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 [EMAIL PROTECTED]
#327 - 964 Heywood Avenue
Victoria, BC CANADA V8V 2Y5
http://mindprod.com
roedy green (250) 361-9093 emergency
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
---------------------------
David A. Bartmess
Software Configuration Manager
http://edingo.net
---
jSyncManager Open Source PDA Sync Program
Developer
http://jsyncmanager.org
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
