On Fri, Dec 11, 2009 at 8:59 PM, Adam Murdoch <[email protected]> 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 http://www.gradle.org
