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: [email protected]
Concertant LLP t: +44 20 7585 2200, +44 20 7193 9203
41 Buckmaster Road, f: +44 8700 516 084 voip: sip:[email protected]
London SW11 1EN, UK m: +44 7770 465 077 skype: russel_winder
signature.asc
Description: This is a digitally signed message part
