As requested by Adam, here are some suggestions for improving the documentation. Note that my perspective is that of a complete newbie, I'm very proficient in Java and Ant, somewhat familiar with maven, and fairly ignorant of both Groovy and Gradle. I'm approaching Gradle as someone who wants a better build than Ant (with a view to migrating a fairly large build script), but doesn't really care about Groovy.

First of all, the build script basics views defining tasks as the most basic thing you could do. I would argue that defining tasks is in fact a fairly advanced usage, and that if gradle does what it says on the tin, is unlikely to be needed for anyone doing standard stuff like compiling some sources and building a file to deploy (war/ear/etc). I'd rename that whole section to a separate document like 'tasks basic guide'.

Going over the Java quickstart next, here are some assumptions that the doc makes that looked like 'magic' to me:

• You talk about the default directories of where gradle expects to find things,and where it'll put them, but no link to how to override the defaults.

• Where does mavenCentral() come from? How would I add another repository? What happens if I don't define any repositories, are there defaults?

• In example 20, I'd list 2 jar files per scope, just so users who don't know groovy see how you can specify multiple items, I'd also make it clear whether compile and testCompile are custom scopes (ie, whether anything else understands those names, or if I could pick entirely arbitrary names). The relationship between the scopes is also unclear, thinking about it, I'm guessing that the names are indeed special and not arbitrary, since some magic knows that testCompile = compile + deps?

• Example 21: Add a link to the full list of properties for the plugin

• Example 22: I'd also add a 2nd property which shows the task being configured, for example to set the working directory (something very common). This brings me to another point (sorry for jumping around, trying to write things down as they occur to me!) which is the distinction between properties and methods. Having the javadoc is great, but as a new user I struggled to find the right syntax until I went on IRC and Adam explained the difference, it'd be worth mentioning this fairly early on, in that in order to find out what you can call/configure in any task, look at the javadocs, and explain how a method listed there maps to gradle/groovy syntax.

• Example 27: Worth being explicit here about : used as directory separator.

• Example 30: Where did spiJar come from? Likewise configurations.runtime. Again keep in mind the groovy ignorance; it'd be worth being explicit about every line and what it does.