From: Luke Daley [mailto:luke.da...@gradleware.com] Sent: Thursday, July 03, 2014 4:08 PM To: KARR, DAVID; dev@gradle.codehaus.org Subject: Re: [gradle-dev] Question about phrase in userguide doc
On 4 July 2014 at 7:53:07 am, KARR, DAVID (dk0...@att.com<mailto: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? I concluded that “Adding Groovy results in an enjoyable and productive experience.” is a worthwhile replacement for that sentence. 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. Acknowledged. Unless a better approach is obvious to me, I’ll stick with small-scale improvements of what’s there. I’ll be glad to consult with others for larger rework. In this particular case, I’d just drop the sentence in question. It’s not adding any value that I can see. If you are doing some proofing (thanks again for this!), don’t hesitate to cull sentences. I’d much rather have fewer, sharper, sentences. I’ll keep that in mind. I’ve seen a few sentences that didn’t provide any value, but the most common pattern I’m seeing are strings of short sentences that could be rephrased as a single sentence that flows more naturally in real speech (just saying it “sotto voce” to yourself is an easy way to see this). — Luke Daley http://www.gradleware.com
