Good to hear some suggestions from another point of view :-)
>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:
Contributions are welcome, we love to increase the usability of Ant.
>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.
The problem is that we have an HTML manual. Where is "the first time"?
We could create a glossary page as you describes in 2. and put it on the
table of content.
"make" - ok, I think it´s historical. When Ant came out, make the only
other build tool and programmers have used C and make. Now people are starting
with Java and Ant. But does it matter to know what "make" is? Where is the
context not clear without knowing that?
>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.
Could be done and linked in the TOC. Where is "start"? Again - it´s html.
And to be honest - I skip usually that parts ...
>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.
Do you had a look into the tutorials? Especially the "Hello World with Ant"
http://ant.apache.org/manual/tutorial-HelloWorldWithAnt.html
>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
There is a WIKI page for that
http://wiki.apache.org/ant/AntSampleFiles
We thought about some reusable buildfiles.
http://wiki.apache.org/ant/Proposals/Antlet
But that is sleeping and awakes from some time to time.
>These recipes allow you to explain best practices. An example
>is 20 times clearer than the best prose.
Something like the examples for the tasks on a higher level?
Do you know "Ant in Anger"?
http://ant.apache.org/ant_in_anger.html
Do you know "The Elements of Ant Style"?
http://wiki.apache.org/ant/TheElementsOfAntStyle
>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.
All are invited.
>I am willing to write, but I would need someone to correct my
>work, since much of Ant is still a mystery to me.
Dont worry. If it´s should be part of the manual, all committers
will have an eye on that.
>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!
Most time you should be able to find something if you think about what you want to do
and search for a task with the same or a similar name. You want to delete something? There
is a <delete> task. You want to compile java sources? It´s done with <javac>
which should
be guessed for a java programmer.
So HOW are you searching for your answers?
Jan
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org
|