On Fri, Jul 4, 2014 at 1:07 AM, Luke Daley <luke.da...@gradleware.com> wrote:
> > > On 4 July 2014 at 7:53:07 am, KARR, DAVID (dk0...@att.com) wrote: > > I'm planning on reading and proofreading the user guide, and submitting > the changes in a PR. I've found a few typos and wordos in just the first > few pages. > > This would be an extremely useful contribution. > > Usually, I find it obvious what the person meant, and can suggest a > better wording. However, sometimes I just can't parse what they were trying > to say. I found one of those ungrokable statements in the "overview" > section, which says: > > "Only by that using Groovy is the fun and productivity gain it can be." > > I can’t decipher it either. > > If I'm reading the history correctly, it looks like Hans wrote this more > than 4 years ago. If Hans isn't around, can someone interpret what he was > trying to say here? > > > That’s right. A lot of the user guide material is from the early days and > is no longer accurate or useful. This is just what happens to documentation > over time; no one’s fault. > > This whole overview chapter needs serious rework. It no longer really > reflects what we hold to be the core values and key messages. I’d be > inclined to scrap it and start again, but that’s a different piece of work. > I think it reflects our core values. - One of our core contribution, next generation declarativeness. - Standardization Toolkit - Powerful, rich executional model - Deep API to embrace the unanticipated - Performance is a key focus - Dependency Management that allows to abstract from your physical structure. - Be like water, integrate with 'what is already there' as a first class concept. The chapter does not a sufficient job though to explain this in a way that people can really get it. One of the still missing pieces for Gradle is that its deep design principles are nowhere explained in sufficient depth. The initial writing of the user guide tried to get some of that across. I think though that the user guide is not the best place for talking about the Gradle philosophy. The user guide should become more lightweight and focus on being a Gradle reference. It is important though, to tell the other part of the story somewhere. I'm working on that. So David, a goal for the refactoring of the user guide could be to kick content like that completely out. I think the dependency management section also has a lot of this. > In this particular case, I’d just drop the sentence in question. It’s not > adding any value that I can see. > In general I think the point I make is very important. It is targeted toward efforts like polyglot Maven, where Groovy is not deeply integrated with the API and which provides a very different experience when using Groovy for describing your build. Hans > If you are doing some proofing (thanks again for this!), don’t hesitate to > cull sentences. I’d much rather have fewer, sharper, sentences. > > — > > Luke Daley > http://www.gradleware.com >
