[GRADLE-1163] Clearer documentation Created: 01/Oct/10  Updated: 10/Feb/17  Resolved: 10/Feb/17

Status: Resolved
Project: Gradle
Affects Version/s: 0.9.1
Fix Version/s: None

Type: Improvement
Reporter: Hani Suleiman Assignee: Unassigned
Resolution: Won't Fix Votes: 1


 Description   

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.


 Comments   
Comment by Benjamin Muschko [ 15/Nov/16 ]

As announced on the Gradle blog we are planning to completely migrate issues from JIRA to GitHub.

We intend to prioritize issues that are actionable and impactful while working more closely with the community. Many of our JIRA issues are inactionable or irrelevant. We would like to request your help to ensure we can appropriately prioritize JIRA issues you’ve contributed to.

Please confirm that you still advocate for your JIRA issue before December 10th, 2016 by:

  • Checking that your issues contain requisite context, impact, behaviors, and examples as described in our published guidelines.
  • Leave a comment on the JIRA issue or open a new GitHub issue confirming that the above is complete.

We look forward to collaborating with you more closely on GitHub. Thank you for your contribution to Gradle!

Comment by Benjamin Muschko [ 10/Feb/17 ]

Thanks again for reporting this issue. We haven't heard back from you after our inquiry from November 15th. We are closing this issue now. Please create an issue on GitHub if you still feel passionate about getting it resolved.

Generated at Wed Jun 30 11:48:34 CDT 2021 using Jira 8.4.2#804003-sha1:d21414fc212e3af190e92c2d2ac41299b89402cf.