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
