On Wed, 27 Jul 2005 10:18:14 -0700, Roedy Green wrote:
IMHO the right place to start this is the wiki, especially since everyone
can right now start to contribute, there are no obstacles. Whether the
content created there is then incorporated into the docs or not is not so
important, HAVING the content at all is the primary goal. You could also
link from the docs to the wiki...
>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]
Ciao, Jürgen
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
