ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From <Jan.Mate...@rzf.fin-nrw.de>
Subject AW: Improving the manual
Date Thu, 28 Jul 2005 06:16:59 GMT
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


Mime
View raw message