Quantcast

where to start for a beginner

classic Classic list List threaded Threaded
20 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

where to start for a beginner

tinca
Hello,

After hours of struggling to get the gradle (groovy) way I must come back to the start line. What is your advice for a beginner (a long time Java programmer), who has little or none knowledge in maven, ivy, groovy, gradle - where to start?
I understand many pieces from what I read and tried till now. It's just they don't come together. As soon as I need to step beyond what I see in the user guide I feel lost. For example, in my previous letter a task jar defines the following:
from sourceSets.main.classes
include [path/to/classes]

I got an error which says: cannot find include() method.
I already know what is sourceSet(s), what is main (I can redefine it for my purposes). "classes" makes the first headache. My guess that this refers to the set of classes produced by compile task (available under buildDir property as defined by project). "from" means a kind of referencing to this set and include is the selection/filtering from that set.
If I do not want to guess what to do? I find SourceSet in the API, this has  a method getClasses that supports my thinking (but how is it related main.classes property(?), I cant see formal correspondence). What is "from" and "include", how do I find their description/meaning? Looking at the Groovy Reference Card does not seem to help.

Can you advice me where to start with my basic understanding after of what I can fully enjoy gradle's wonders?

Your help much appreciated!
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Steve Ebersole
I am not sure of TheBestWay as I am still learning gradle myself coming from a background of not knowing groovy at all.  What really started 'putting the pieces in place' for me was actually writing a plugin+task as I got to see some of the inner workings.  

Sourcesets, for example, as well as its 'directories', are largely virtual concepts.  As you reference properties et al of the sourceset gradle resolves them dynamically.  Very cool and very powerful stuff.

Anyway that really started helping me get into it.

-- Sent from my Palm Prē

[hidden email]
http://hibernate.org

tinca wrote:


Hello,

After hours of struggling to get the gradle (groovy) way I must come back to
the start line. What is your advice for a beginner (a long time Java
programmer), who has little or none knowledge in maven, ivy, groovy, gradle
- where to start?
I understand many pieces from what I read and tried till now. It's just they
don't come together. As soon as I need to step beyond what I see in the user
guide I feel lost. For example, in my previous letter a task jar defines the
following:
from sourceSets.main.classes
include [path/to/classes]

I got an error which says: cannot find include() method.
I already know what is sourceSet(s), what is main (I can redefine it for my
purposes). "classes" makes the first headache. My guess that this refers to
the set of classes produced by compile task (available under buildDir
property as defined by project). "from" means a kind of referencing to this
set and include is the selection/filtering from that set.
If I do not want to guess what to do? I find SourceSet in the API, this has
a method getClasses that supports my thinking (but how is it related
main.classes property(?), I cant see formal correspondence). What is "from"
and "include", how do I find their description/meaning? Looking at the
Groovy Reference Card does not seem to help.

Can you advice me where to start with my basic understanding after of what I
can fully enjoy gradle's wonders?

Your help much appreciated!
--
View this message in context: http://old.nabble.com/where-to-start-for-a-beginner-tp26741219p26741219.html
Sent from the gradle-user mailing list archive at Nabble.com.


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Cédric Beust ♔
In reply to this post by tinca
For what it's worth, I have had (and still do) the exact same experience.

To me, the style guide is a bit similar to trying to learn a language by learning premade sentences.  There is too much emphasis on "how" and not enough on "why".

I think one of my main problems from the code snippets there is that I can't figure out which ones are "keywords" and which ones must be defined or included.

For example, the first real example (5.4): 


dependencies {
    compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
    testCompile group: 'junit', name: 'junit', version: '4.+'
}
What is compile?  And testCompile?  They are not explained before.  Actually, testCompile is never explained anywhere and that's the only place it ever appears in the doc. 

Every single code snippet in this documentation contains things like that and it's extremely frustrating.  I want to like Gradle but you really need to make it much easier for people not interested in diving deep in the source...

As I said in a previous message, walking through a simple migration guide from ant would be a great start:  pick a standard Java project with sources, tests, local jar dependencies, external jar dependencies and a packaging target, and step by step, show how to convert it to Gradle.

-- 
Cédric





On Fri, Dec 11, 2009 at 1:30 AM, tinca <[hidden email]> wrote:

Hello,

After hours of struggling to get the gradle (groovy) way I must come back to
the start line. What is your advice for a beginner (a long time Java
programmer), who has little or none knowledge in maven, ivy, groovy, gradle
- where to start?
I understand many pieces from what I read and tried till now. It's just they
don't come together. As soon as I need to step beyond what I see in the user
guide I feel lost. For example, in my previous letter a task jar defines the
following:
from sourceSets.main.classes
include [path/to/classes]

I got an error which says: cannot find include() method.
I already know what is sourceSet(s), what is main (I can redefine it for my
purposes). "classes" makes the first headache. My guess that this refers to
the set of classes produced by compile task (available under buildDir
property as defined by project). "from" means a kind of referencing to this
set and include is the selection/filtering from that set.
If I do not want to guess what to do? I find SourceSet in the API, this has
a method getClasses that supports my thinking (but how is it related
main.classes property(?), I cant see formal correspondence). What is "from"
and "include", how do I find their description/meaning? Looking at the
Groovy Reference Card does not seem to help.

Can you advice me where to start with my basic understanding after of what I
can fully enjoy gradle's wonders?

Your help much appreciated!
--
View this message in context: http://old.nabble.com/where-to-start-for-a-beginner-tp26741219p26741219.html
Sent from the gradle-user mailing list archive at Nabble.com.


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email





Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Paul Speed-2
First of all, I totally agree with the comments regarding the
documentation.  I always feel bad feeling that way because there really
is a lot of good stuff in the docs... I just always feel like I can
never find it as a reference.

To your specific example, there is a certain amount of the documentation
that seems to require one to already understand what is going on.  For
example, I looked at the below and knew that "compile" and "testCompile"
where "Configurations"... and more specifically configurations put
together by the Java plugin.  So I went and found table 18.5 and Figure
18.2 which both provide some context of these configurations.

An index would be nice and I hear they are working on it but to my mind
I really miss the quick reference of something like the ANT docs.  "How
do I configure the jar task again?" click click "Ah, there are all of
the parameters and descriptions and several examples showing them in
practice."

...though even that expects some prior understanding of ANT mechanics I
guess.

I actually have a desire to contribute to the docs in some way but I'm
still not confident enough in any area that I feel I know what I'm
talking about. ;)

-Paul

Cédric Beust ♔ wrote:

> For what it's worth, I have had (and still do) the exact same experience.
>
> To me, the style guide is a bit similar to trying to learn a language by
> learning premade sentences.  There is too much emphasis on "how" and not
> enough on "why".
>
> I think one of my main problems from the code snippets there is that I
> can't figure out which ones are "keywords" and which ones must be
> defined or included.
>
> For example, the first real example (5.4):
>
>
> dependencies {
>     compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
>     testCompile group: 'junit', name: 'junit', version: '4.+'
> }
>
> What is compile?  And testCompile?  They are not explained before.
>  Actually, testCompile is never explained anywhere and that's the only
> place it ever appears in the doc.
>
> Every single code snippet in this documentation contains things like
> that and it's extremely frustrating.  I want to like Gradle but you
> really need to make it much easier for people not interested in diving
> deep in the source...
>
> As I said in a previous message, walking through a simple migration
> guide from ant would be a great start:  pick a standard Java project
> with sources, tests, local jar dependencies, external jar dependencies
> and a packaging target, and step by step, show how to convert it to Gradle.
>
> --
> **/*Cédric*
> /
>
>
>
>
> On Fri, Dec 11, 2009 at 1:30 AM, tinca <[hidden email]
> <mailto:[hidden email]>> wrote:
>
>
>     Hello,
>
>     After hours of struggling to get the gradle (groovy) way I must come
>     back to
>     the start line. What is your advice for a beginner (a long time Java
>     programmer), who has little or none knowledge in maven, ivy, groovy,
>     gradle
>     - where to start?
>     I understand many pieces from what I read and tried till now. It's
>     just they
>     don't come together. As soon as I need to step beyond what I see in
>     the user
>     guide I feel lost. For example, in my previous letter a task jar
>     defines the
>     following:
>     from sourceSets.main.classes
>     include [path/to/classes]
>
>     I got an error which says: cannot find include() method.
>     I already know what is sourceSet(s), what is main (I can redefine it
>     for my
>     purposes). "classes" makes the first headache. My guess that this
>     refers to
>     the set of classes produced by compile task (available under buildDir
>     property as defined by project). "from" means a kind of referencing
>     to this
>     set and include is the selection/filtering from that set.
>     If I do not want to guess what to do? I find SourceSet in the API,
>     this has
>     a method getClasses that supports my thinking (but how is it related
>     main.classes property(?), I cant see formal correspondence). What is
>     "from"
>     and "include", how do I find their description/meaning? Looking at the
>     Groovy Reference Card does not seem to help.
>
>     Can you advice me where to start with my basic understanding after
>     of what I
>     can fully enjoy gradle's wonders?
>
>     Your help much appreciated!
>     --
>     View this message in context:
>     http://old.nabble.com/where-to-start-for-a-beginner-tp26741219p26741219.html
>     Sent from the gradle-user mailing list archive at Nabble.com.
>
>
>     ---------------------------------------------------------------------
>     To unsubscribe from this list, please visit:
>
>        http://xircles.codehaus.org/manage_email
>
>
>
>
>


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

tinca
In reply to this post by Cédric Beust ♔
Cédric Beust ♔ wrote
For what it's worth, I have had (and still do) the exact same experience.

To me, the style guide is a bit similar to trying to learn a language by
learning premade sentences.  There is too much emphasis on "how" and not
enough on "why".
..
Hello Cedric,

Thanks for sharing your thoughts, at least I do not feel lonely :-)
Had I found your post earlier, I would have joined...

I want gradle, too. Used ant for a time and felt the need to use something more convenient and powerful, but maven has always taken me aback. If I have to learn something new anyway I decided on gradle to be that thing. (Just a side note, when doing the same with a testing framework TestNG was (and still is) the winner :-)
I feel the same with the keyword thing. Although the concepts like configures, dependencies are more or less explained and there are simple examples, many times that is not enough. The many ways of doing things is disturbing for a beginner. I do not know what is simply just another option or something that cannot be done otherwise. (One such thing was the possibility to use simple jar name for dependency in case of a local repository. Later when I found useful using Lists for defining repo dirs, jar naming ceased to work, had to change to artifact only notation).

Nevertheless, I would like to thank the people of gradle for their great work! What I say is just a voice of one of their "customer". I am sure they know that when interest in their product is getting high the barrier to it becomes immediately visible for many of us.

Thanks!
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

tinca
In reply to this post by Steve Ebersole
Steve Ebersole wrote
I am not sure of TheBestWay as I am still learning gradle myself coming from a background of not knowing groovy at all.  What really started 'putting the pieces in place' for me was actually writing a plugin+task as I got to see some of the inner workings.  
...
Hello Steve,

Thanks for your thougths, too. I agree that one of the most powerful approach is what you describe. Many times I follow that path. Now, however, I am doing many new things at the same time. My focus is on other aspects of development, I do not have time for more (I know, do not start with too many new technologies in a project...). But I do not want an ant build! :-)
This is where a barrier to a new thing is magnified ;-)

Thanks!
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Russel Winder-2
In reply to this post by tinca
The core problem in trying to be helpful here is that you give too
little information about what you are trying to do to be concretely
helpful.

Apologies also if I am wading in half way through a thread and this
information has been given earlier but . . . well you do say "back to
the start line".

On Fri, 2009-12-11 at 01:30 -0800, tinca wrote:
> Hello,
>
> After hours of struggling to get the gradle (groovy) way I must come back to
> the start line. What is your advice for a beginner (a long time Java
> programmer), who has little or none knowledge in maven, ivy, groovy, gradle
> - where to start?

If you don't know Maven is all your previous experience with Ant?

The place to start is at the beginning.  What does your project look
like?  Is it structure according to the Maven standard structure or
something different?  What sort of build product are you trying to
create?

> I understand many pieces from what I read and tried till now. It's just they
> don't come together. As soon as I need to step beyond what I see in the user
> guide I feel lost. For example, in my previous letter a task jar defines the
> following:
> from sourceSets.main.classes
> include [path/to/classes]

Did you start with a trivial project and then add to it to to make the
project bigger and more like the final project you have, or are you
trying to work directly with the final project?

> I got an error which says: cannot find include() method.

Without seeing the file it is impossible to interpret the error you are
seeing.  Sorry.

> I already know what is sourceSet(s), what is main (I can redefine it for my
> purposes). "classes" makes the first headache. My guess that this refers to
> the set of classes produced by compile task (available under buildDir
> property as defined by project). "from" means a kind of referencing to this
> set and include is the selection/filtering from that set.

Again without the file it is difficult to say anything constructive let
alone useful.

> If I do not want to guess what to do? I find SourceSet in the API, this has
> a method getClasses that supports my thinking (but how is it related
> main.classes property(?), I cant see formal correspondence). What is "from"
> and "include", how do I find their description/meaning? Looking at the
> Groovy Reference Card does not seem to help.
>
> Can you advice me where to start with my basic understanding after of what I
> can fully enjoy gradle's wonders?

First play with a trivial standard Maven structured project.
Then play with the structure and make the build work.
Then put it back as standard is good :-)
Then try various experiments leading towards the final project.

>
> Your help much appreciated!

Hopefully the above helps start the process of helping.

--
Russel.
=============================================================================
Dr Russel Winder      Partner
                                            xmpp: [hidden email]
Concertant LLP        t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,   f: +44 8700 516 084   voip: sip:[hidden email]
London SW11 1EN, UK   m: +44 7770 465 077   skype: russel_winder

signature.asc (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Russel Winder-2
In reply to this post by Cédric Beust ♔
On Fri, 2009-12-11 at 08:37 -0800, Cédric Beust ♔ wrote:
> For what it's worth, I have had (and still do) the exact same
> experience.
>
I am also in two minds about the user guide.  Where it is good it is
very good and very helpful where it is bad is is appalling.

I think the real problem with the user guide is that it is trying to be
a reference, a tutorial and an integration test.  All the frustrations
people are mentioning are clear consequences of this conflict.

(I have more or less agreed to write an introductory book on using
Gradle but I haven't actually started yet as a flood of other things
have got in the way. :-(
>
> To me, the style guide is a bit similar to trying to learn a language
> by learning premade sentences.  There is too much emphasis on "how"
> and not enough on "why".

Another part of the problem is that the user guide is being used as a
tool for driving integration testing and I am not sure the various
purposes are melded together appropriately just now.

> I think one of my main problems from the code snippets there is that I
> can't figure out which ones are "keywords" and which ones must be
> defined or included.
>
My problem of the moment in integTest, I am seeing traditional dynamic
language weirdnesses that using the symbol in some places things just
work and in others it all breaks.

> For example, the first real example (5.4):
>
> dependencies {
>     compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
>     testCompile group: 'junit', name: 'junit', version: '4.+'
> }
> What is compile?  And testCompile?  They are not explained before.
>  Actually, testCompile is never explained anywhere and that's the only
> place it ever appears in the doc.
>
compile and testCompile are the names of configurations that are defined
in the Java plugin.
>
> Every single code snippet in this documentation contains things like
> that and it's extremely frustrating.  I want to like Gradle but you
> really need to make it much easier for people not interested in diving
> deep in the source...
>
This for me is an aspect of the fact that the code snippets are being
used for integration testing as well as documentation.

I am switching Gant from a Gant build to a Gradle build.  Most of it
went trivially once I got the multi-project architecture in place (I
tried it in Maven and failed dismally, with Gradle it fell into place
quite nicely).  However there are things that I find frustratingly
annoying so I understand your frustration.

The very worst outcome here would be for you to have a bad taste in your
mouth about Gradle.  Even worse if you blog about that :-)

> As I said in a previous message, walking through a simple migration
> guide from ant would be a great start:  pick a standard Java project
> with sources, tests, local jar dependencies, external jar dependencies
> and a packaging target, and step by step, show how to convert it to
> Gradle.
>
I think this is needed as an appendix to the user guide.  Perhaps we can
use a wiki somewhere (Hans, Adam, where is an appropriate page to start
this?).

People put up project structures as children of the top level page and
then we can have the Ant build and/or Maven build as a child of that and
a Gradle build as another child.

This material would help immediately in that form and would also be
great input to the user guide and the book.

Another issue is that people need "known to work" examples of real
projects.  I can offer the Gant project (Bazaar branch at lp:gant) and
my ADS library (which uses TestNG :-) (Bazaar branch at
http://www.russel.org.uk/Bazaar/ADS.)

I had an Ant build for Gant some time back and that will be there in the
history, ditto the ADS library.  ADS still has a Maven build.

Hopefully this can move us on in a constructive, helpful and not
frustrating way.


--
Russel.
=============================================================================
Dr Russel Winder      Partner
                                            xmpp: [hidden email]
Concertant LLP        t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,   f: +44 8700 516 084   voip: sip:[hidden email]
London SW11 1EN, UK   m: +44 7770 465 077   skype: russel_winder

signature.asc (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Paul Speed-2
Reading this, I started to wonder if a consistent color-coding of the
examples might help.  I don't know if the way the docs are generated
support this but knowing at a glance which 'word' is a built-in call
(like dependencies) versus a task name versus a configuration name might
at least help.

...I may gen up some examples to illustrate what I'm talking about with
respect to clarity.

-Paul

Russel Winder wrote:

> On Fri, 2009-12-11 at 08:37 -0800, Cédric Beust ♔ wrote:
>
>> For example, the first real example (5.4):
>>
>> dependencies {
>>     compile group: 'commons-collections', name: 'commons-collections', version: '3.2'
>>     testCompile group: 'junit', name: 'junit', version: '4.+'
>> }
>> What is compile?  And testCompile?  They are not explained before.
>>  Actually, testCompile is never explained anywhere and that's the only
>> place it ever appears in the doc.
>>
> compile and testCompile are the names of configurations that are defined
> in the Java plugin.



---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Russel Winder-2
In reply to this post by Paul Speed-2
Paul,

On Fri, 2009-12-11 at 11:57 -0500, Paul Speed wrote:
> First of all, I totally agree with the comments regarding the
> documentation.  I always feel bad feeling that way because there really
> is a lot of good stuff in the docs... I just always feel like I can
> never find it as a reference.

I think Hans, Adam and co have done a great job to date.  Personally I
think Gradle is the future of build on the JVM.  Couple it with SCons
(or Waf) for C, C++, LaTeX, and Python, and I have all the build tools I
think I'll ever need.

Sadly both Gradle and SCons suffer somewhat from the same problem, there
is a lot of good bits of documentation, but the whole is sadly lacking.
For Gradle this is sort of understandable as the emphasis to date has
been on making builds work.  And the project is only just over two years
old!  (Gradle was born out of a meeting about Gant and its future held
at Grails eXchange in 2007.)

> To your specific example, there is a certain amount of the documentation
> that seems to require one to already understand what is going on.  For
> example, I looked at the below and knew that "compile" and "testCompile"
> where "Configurations"... and more specifically configurations put
> together by the Java plugin.  So I went and found table 18.5 and Figure
> 18.2 which both provide some context of these configurations.

This is very much "good bits, shame about the whole".  This is really I
think because no-one has tackled the whole as yet.  Hans did a great job
of starting the documentation using LaTeX, it has now been moved to
DocBook/XML but somewhere along the line the role of "editor of the
whole" never got refilled.  The issue of cross-references, storylines,
completeness, etc. have I think not been addressed.  Basically due to
shortage of person hours.

> An index would be nice and I hear they are working on it but to my mind
> I really miss the quick reference of something like the ANT docs.  "How
> do I configure the jar task again?" click click "Ah, there are all of
> the parameters and descriptions and several examples showing them in
> practice."

I think it would be really great if everyone didn't say "I hear they are
working on it" but instead said "I'll go and add these things I found to
the documentation".  We need to think of the documentation as our
responsibility.  The documentation is there in the (sadly Git)
repository, so people can take a clone, make amendments and submit
patches for checking and merging.

Even providing patches that ask questions without providing answers, or
propose new sections, are way better than comments on the mailing list.
Many reasons mostly to do with community and culture, but also to do
with ownership.  We own the problem of making the documentation good
enough for us to work with.  By providing the structure and questions we
need answering so that the people who know just have to fill in the
answers, the documentation will get a lot better very quickly.

If using the repository is too big a deal lets use a wiki and then
someone can transfer the material into the repository.  Lighweight
processes and infrastructure always help :-)

> ...though even that expects some prior understanding of ANT mechanics I
> guess.
>
> I actually have a desire to contribute to the docs in some way but I'm
> still not confident enough in any area that I feel I know what I'm
> talking about. ;)

That is great to hear.  Gradle needs more people hours to make is a
great project.  What is needed is an infrastructure and a workflow to
allow people to contribute as and when they can.  The docs clearly need
help so effort there can only be good.  What tools would enable you to
contribute easily and quickly?  If the system as is doesn't support that
then a change is needed.

--
Russel.
=============================================================================
Dr Russel Winder      Partner
                                            xmpp: [hidden email]
Concertant LLP        t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,   f: +44 8700 516 084   voip: sip:[hidden email]
London SW11 1EN, UK   m: +44 7770 465 077   skype: russel_winder

signature.asc (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

John Murph
In reply to this post by Russel Winder-2
On Fri, Dec 11, 2009 at 1:05 PM, Russel Winder <[hidden email]> wrote:

I think the real problem with the user guide is that it is trying to be
a reference, a tutorial and an integration test.  All the frustrations
people are mentioning are clear consequences of this conflict.


This is the heart of the problem, I think.  We need a tutorial that explains the concepts (more of the "why" with some of the "how" thrown in) and shows simple code samples.  Then we need a reference manual that gives all the available options.  Steve Appling had wanted to do this, but has not had time.  I'm not much of a writer (or maybe I just don't like it...) so I don't think I would be much help either.  I really think someone other than Hans or Adam should write it though, and then let them fix all the mistakes.  That way we can avoid the "knowing it too well" syndrome that affects many user guides (including Gradle's current one).

--
John Murph
Automated Logic Research Team
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Russel Winder-2
On Fri, 2009-12-11 at 13:28 -0500, John Murph wrote:

> On Fri, Dec 11, 2009 at 1:05 PM, Russel Winder
> <[hidden email]> wrote:
>        
>         I think the real problem with the user guide is that it is
>         trying to be
>         a reference, a tutorial and an integration test.  All the
>         frustrations
>         people are mentioning are clear consequences of this conflict.
>        
>
> This is the heart of the problem, I think.  We need a tutorial that
> explains the concepts (more of the "why" with some of the "how" thrown
> in) and shows simple code samples.  Then we need a reference manual
> that gives all the available options.  Steve Appling had wanted to do
> this, but has not had time.  I'm not much of a writer (or maybe I just
> don't like it...) so I don't think I would be much help either.  I
> really think someone other than Hans or Adam should write it though,
> and then let them fix all the mistakes.  That way we can avoid the
> "knowing it too well" syndrome that affects many user guides
> (including Gradle's current one).
>
I think this is an opportunity for a community based approach.  In the
end every document benefits from having a last person who writes
everything, but to get material quickly people need to contribute.
Wikis are probably a good tool for this.  If people can find it easy to
put questions and answers into a place then an editor can merge it into
something.

Actually perhaps we can do the book this way.  Everybody contributes
material under Creative Commons licence then one or two people edit the
whole lot and get it into a form O'Reilly, APress, Manning, or Pragmatic
Programmers will take?

--
Russel.
=============================================================================
Dr Russel Winder      Partner
                                            xmpp: [hidden email]
Concertant LLP        t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,   f: +44 8700 516 084   voip: sip:[hidden email]
London SW11 1EN, UK   m: +44 7770 465 077   skype: russel_winder

signature.asc (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Cédric Beust ♔


On Fri, Dec 11, 2009 at 10:35 AM, Russel Winder <[hidden email]> wrote:
I think this is an opportunity for a community based approach.

In my experience, community based documentations always end up in a disaster (especially wiki based ones).  You end up trading quality for quantity and you lose a lot of consistency.

I'd rather see a two-three page one person guide than fifty pages of mishmash information cobbled together without overall vision.

--
Cédric


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Russel Winder-2
On Fri, 2009-12-11 at 10:43 -0800, Cédric Beust ♔ wrote:

> On Fri, Dec 11, 2009 at 10:35 AM, Russel Winder
> <[hidden email]> wrote:
>         I think this is an opportunity for a community based
>         approach.
>
> In my experience, community based documentations always end up in a
> disaster (especially wiki based ones).  You end up trading quality for
> quantity and you lose a lot of consistency.

Only if the wiki is the final product -- I agree community written
documentation is generally not great.  For me community input is input
to ensure the final document attacks the problems that people actually
have.  At the end of the day there is no substitute for having one
person write the whole of the final content.
>
> I'd rather see a two-three page one person guide than fifty pages of
> mishmash information cobbled together without overall vision.
>
I'd rather have the fifty page one-person guide myself :-)

I agree about overall vision, I had thought I'd said that.  Clearly I
didn't.  Sorry.

--
Russel.
=============================================================================
Dr Russel Winder      Partner
                                            xmpp: [hidden email]
Concertant LLP        t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road,   f: +44 8700 516 084   voip: sip:[hidden email]
London SW11 1EN, UK   m: +44 7770 465 077   skype: russel_winder

signature.asc (204 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

John Murph
In reply to this post by Cédric Beust ♔
2009/12/11 Cédric Beust ♔ <[hidden email]>


On Fri, Dec 11, 2009 at 10:35 AM, Russel Winder <[hidden email]> wrote:
I think this is an opportunity for a community based approach.

In my experience, community based documentations always end up in a disaster (especially wiki based ones).  You end up trading quality for quantity and you lose a lot of consistency.

I'd rather see a two-three page one person guide than fifty pages of mishmash information cobbled together without overall vision.

--
Cédric



I think this is why Russell said "In the end every document benefits from having a last person who writes everything...."  The idea, I think, is to get the content from everyone and then have a single person put it together into a cohesive whole.  This person will do the lion's share of the work, but not having to generate all the content as well is a huge burden removed.  With this approach, the idea is that one person would not have to dedicate as much time which makes the whole effort more likely to happen.


--
John Murph
Automated Logic Research Team
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Cédric Beust ♔
Yes, sorry for missing this, Russell.

Maybe the best of both worlds is an internal wiki from which one person can mine the necessary information and put it together in one coherent public doc.

--
Cédric



On Fri, Dec 11, 2009 at 11:05 AM, John Murph <[hidden email]> wrote:
2009/12/11 Cédric Beust ♔ <[hidden email]>



On Fri, Dec 11, 2009 at 10:35 AM, Russel Winder <[hidden email]> wrote:
I think this is an opportunity for a community based approach.

In my experience, community based documentations always end up in a disaster (especially wiki based ones).  You end up trading quality for quantity and you lose a lot of consistency.

I'd rather see a two-three page one person guide than fifty pages of mishmash information cobbled together without overall vision.

--
Cédric



I think this is why Russell said "In the end every document benefits from having a last person who writes everything...."  The idea, I think, is to get the content from everyone and then have a single person put it together into a cohesive whole.  This person will do the lion's share of the work, but not having to generate all the content as well is a huge burden removed.  With this approach, the idea is that one person would not have to dedicate as much time which makes the whole effort more likely to happen.


--
John Murph
Automated Logic Research Team



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Adam Murdoch-2
In reply to this post by Russel Winder-2


On 12/12/09 5:24 AM, Russel Winder wrote:

>
>> An index would be nice and I hear they are working on it but to my mind
>> I really miss the quick reference of something like the ANT docs.  "How
>> do I configure the jar task again?" click click "Ah, there are all of
>> the parameters and descriptions and several examples showing them in
>> practice."
>>      
> I think it would be really great if everyone didn't say "I hear they are
> working on it" but instead said "I'll go and add these things I found to
> the documentation".  We need to think of the documentation as our
> responsibility.  The documentation is there in the (sadly Git)
> repository, so people can take a clone, make amendments and submit
> patches for checking and merging.
>
> Even providing patches that ask questions without providing answers, or
> propose new sections, are way better than comments on the mailing list.
> Many reasons mostly to do with community and culture, but also to do
> with ownership.  We own the problem of making the documentation good
> enough for us to work with.  By providing the structure and questions we
> need answering so that the people who know just have to fill in the
> answers, the documentation will get a lot better very quickly.
>
>    

Big +1 to this.

We really need contributions from the community if we are to end up with
high quality documentation. I don't feel like I have the technical
writing experience to produce a good quality user guide on my own, and I
really would like to draw on the experience and energy of the community
to help craft it. I also feel like I'm too close to the problem. I
already know how the thing works, and it's very easy to assume that the
reader knows more than they do.

These mailing list postings are good in some respect, as we get some
valuable feedback about what isn't working. But it would be so much
nicer if instead we ended up with some incremental improvement to the
documentation. Your contributions don't have to be fully formed
documentation. Questions, bullet points, better examples, section
headers, restructuring, fixing the words, adding an index, anything is
useful. Don't worry that you don't know Gradle that well. Just jump in,
and you will learn what you need to know soon enough.

Don't forget that it's quite easy to contribute to the documentation:
http://docs.codehaus.org/display/GRADLE/How+to+build+the+documentation

If that's too hard, there's also a place on the wiki where you can add
ideas for additional content:
http://docs.codehaus.org/display/GRADLE/User+guide

And then there's cookbook for collecting 'how do I?' content:
http://docs.codehaus.org/display/GRADLE/Cookbook

It really isn't hard to contribute.


--
Adam Murdoch
Gradle Developer
http://www.gradle.org


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

Tomek Kaczanowski-3
In reply to this post by Paul Speed-2
> Reading this, I started to wonder if a consistent color-coding of the
> examples might help.  I don't know if the way the docs are generated support
> this but knowing at a glance which 'word' is a built-in call (like
> dependencies) versus a task name versus a configuration name might at least
> help.
Paul, I like this idea very much. Some time ago I also thought about
it and even did some research on Docbook/XSLT in terms of code
highlighting. I added a JIRA issue for this:
http://jira.codehaus.org/browse/GRADLE-779
Please vote for this is you think it is important.

--
Tomek

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

hans_d
Administrator
In reply to this post by Adam Murdoch-2


On Fri, Dec 11, 2009 at 8:59 PM, Adam Murdoch <[hidden email]> wrote:


On 12/12/09 5:24 AM, Russel Winder wrote:

An index would be nice and I hear they are working on it but to my mind
I really miss the quick reference of something like the ANT docs.  "How
do I configure the jar task again?" click click "Ah, there are all of
the parameters and descriptions and several examples showing them in
practice."
   
I think it would be really great if everyone didn't say "I hear they are
working on it" but instead said "I'll go and add these things I found to
the documentation".  We need to think of the documentation as our
responsibility.  The documentation is there in the (sadly Git)
repository, so people can take a clone, make amendments and submit
patches for checking and merging.

Even providing patches that ask questions without providing answers, or
propose new sections, are way better than comments on the mailing list.
Many reasons mostly to do with community and culture, but also to do
with ownership.  We own the problem of making the documentation good
enough for us to work with.  By providing the structure and questions we
need answering so that the people who know just have to fill in the
answers, the documentation will get a lot better very quickly.

 

Big +1 to this.

We really need contributions from the community if we are to end up with high quality documentation. I don't feel like I have the technical writing experience to produce a good quality user guide on my own, and I really would like to draw on the experience and energy of the community to help craft it. I also feel like I'm too close to the problem. I already know how the thing works, and it's very easy to assume that the reader knows more than they do.

These mailing list postings are good in some respect, as we get some valuable feedback about what isn't working. But it would be so much nicer if instead we ended up with some incremental improvement to the documentation. Your contributions don't have to be fully formed documentation. Questions, bullet points, better examples, section headers, restructuring, fixing the words, adding an index, anything is useful. Don't worry that you don't know Gradle that well. Just jump in, and you will learn what you need to know soon enough.

Don't forget that it's quite easy to contribute to the documentation: http://docs.codehaus.org/display/GRADLE/How+to+build+the+documentation

If that's too hard, there's also a place on the wiki where you can add ideas for additional content: http://docs.codehaus.org/display/GRADLE/User+guide

And then there's cookbook for collecting 'how do I?' content: http://docs.codehaus.org/display/GRADLE/Cookbook

It really isn't hard to contribute.
 
I would also like to mention the external resources section in our Wiki: http://docs.codehaus.org/display/GRADLE/External+Resources
Quite a few people have written excellent blog series about how to use Gradle.

I definitely see the documentation issues raised in this thread. From the Gradle developers side it is also an issue of scarce resources as we want to get 1.0 out as soon as possible (first there will be 0.9). Which is again also important for the documentation in whatever form (user's guide, articles, blogs, ...). A stable API makes for stable documentation. 

- Hans

--
Hans Dockter
Gradle Project Manager
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: where to start for a beginner

tinca
In reply to this post by Russel Winder-2
Hello Russel,

Russel Winder-4 wrote:
>The core problem in trying to be helpful here is that you give too
>little information about what you are trying to do to be concretely
>helpful.
In this topic it was not my intention to write about a specific problem.

...
>If you don't know Maven is all your previous experience with Ant?
Yes.

>The place to start is at the beginning.  What does your project look
>like?  Is it structure according to the Maven standard structure or
>something different?  What sort of build product are you trying to
>create?
I have no problem with my project structure. I could tailor my gradle.build.
It was more or less straightforward experience to set up my local repo so hat I can
compile the project.

>Did you start with a trivial project and then add to it to to make the
>project bigger and more like the final project you have, or are you
>trying to work directly with the final project?
This is a new project and is rather simple at present.

>> I got an error which says: cannot find include() method.

>Without seeing the file it is impossible to interpret the error you are
>seeing.  Sorry.
OK. I started a topic a bit earlier describing the problem.
http://old.nabble.com/Could-not-find-method-include()-td26740547.html
I always try to give enough context to the problem, but it may happen that now
this was not enough.

>> I already know what is sourceSet(s), what is main (I can redefine it for my
>> purposes). "classes" makes the first headache. My guess that this refers to
>> the set of classes produced by compile task (available under buildDir
>> property as defined by project). "from" means a kind of referencing to this
>> set and include is the selection/filtering from that set.

>Again without the file it is difficult to say anything constructive let
>alone useful.
I am talking about this in a generic context to illustrate what kind of
problems I face when trying to understand things within gradle.
I do not want to flood the list with too basic question. I don't mind to work
through the hard way. Just wanted to make sign that this feels too hard way
compared to what I think it ought to be.

...
>> Can you advice me where to start with my basic understanding after of what I
>> can fully enjoy gradle's wonders?

>First play with a trivial standard Maven structured project.
>Then play with the structure and make the build work.
>Then put it back as standard is good :-)
>Then try various experiments leading towards the final project.
As said, the first three was not a problem. The last point is what I am
following :-)

>Hopefully the above helps start the process of helping.
Thank you for paying attention to my problem!

Zsolt
Loading...