On Fri, 2009-12-11 at 13:28 -0500, John Murph wrote: > On Fri, Dec 11, 2009 at 1:05 PM, Russel Winder > <[email protected]> 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: [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
