As one who writes documentation professionally, I see the impedance mismatch between Greg's desires and Javadoc. AFAICT, Greg wants to know "why"; Javadoc describes "how". A toolkit that evolves as rapidly as GWT does not lend itself to in-depth "why" documentation.
I see that the GWT team puts substantial effort into sample programs; which examples may be as close as we can get to "why" combined with "how". I'm sure that the GWT team would welcome documentation contributions. The issue I have is ensuring such contributions have a lifetime > 6 months. On Tue, Dec 7, 2010 at 3:17 PM, A. Stevko <[email protected]> wrote: > Greg - I admire your position on the quality of documentation. > IMO, a measure of a sw engineer is not how much arcana he knows but rather > knowing where to find it. > Javadocs have long been a great source for the many of the details that I > face daily although they typically suck for usability. > > A question to the group - Is it possible to crowd source the GWT and GAE > javadocs? > If we can't get to the source to augment the documentation, how about some > kind of sister wiki site that can be the proving ground for training and > usability improvements while also providing a very specific location to > discuss API meta issues. > > The first thought on an approach to this is to have the javadoc template > automatically write external links into a google site or similar. > > --Andy Stevko > > > On Tue, Dec 7, 2010 at 12:30 PM, Jeff Schwartz <[email protected]>wrote: > >> Good luck! >> >> >> >> On Tue, Dec 7, 2010 at 3:08 PM, Greg Dougherty < >> [email protected]> wrote: >> >>> Hi Jeff, >>> >>> If it ever comes to be the situation that the only way I can do >>> programming is on the web, then I'll waste the time to learn the >>> current iteration of web programming. But life is currently not so >>> dim or dreary, and doesn't look to be that way any time soon. (And if >>> I am going to take the time to "read, read, read" on new programming >>> ideas, it'll be on the Android (where there's a decent job market, and >>> worthwhile development tools) or the iPhone (I've got one iPhone app >>> out, but I'd like to learn more networking, and some of the newer >>> technologies, not on a constantly changing "standards" body heavily >>> influenced by Microsoft and Internet Explorer.) I have a finite >>> supply of "learn" time, and I have thigns that, for me, are far better >>> ways to spend it than reading W3C documents. >>> >>> Let me put it another way: I have absolutely NO desire to be a "master >>> Web applications developer". If I wanted to be one of those, I >>> wouldn't be using GWT. I'd be rolling my own. >>> >>> I took a look at SpringToolsSuite and Spring Roo. Their documentation >>> sucks, their tutorials are out of date, their integration with Eclipse >>> is poor, and the support on the forums is weak. So, since I AM a good >>> SQL developer, I said the heck with that, and rolled my own for my >>> current project. And do not regret the choice at all. The difference >>> is that I find SQL a lot more interesting than JavaScript. >>> >>> Look, I'm glad that there are people out there who WANT to dig into >>> the arcana of web programming. I'm not one of them. I'm someone who >>> wants to solve other problems. It was my impression that GWT exists >>> to serve the people who want to solve those other problems, and don't >>> want to have to dig in to that web BS (like worrying about IE vs. >>> FF). If that IS GWT's purpose, then their documentation sucks, and is >>> not in line with their purpose. >>> >>> If that ISN'T GWTs purpose, what is? >>> >>> Greg >>> >>> On Dec 7, 11:24 am, Jeff Schwartz <[email protected]> wrote: >>> > Hi Greg, >>> > >>> > I have been in IT for a very long time. You see, I am what the youngins >>> > sometimes refer to as an ol' fart :). As a matter of fact, I've been a >>> > developer in one form or another for so long that everything else prior >>> to >>> > that seems to me to be prehistory - a vague sense of something there >>> but not >>> > having much substance (oh GOD, help me lol). >>> > >>> > My point is that as technologies advance I try to stay current and for >>> those >>> > technologies that I have or will chose to base a career on I've tried >>> to >>> > master them to the best of my ability. That means giving up lots of >>> personal >>> > time to read up on everything I can get my hands on. Why the story? >>> Because >>> > I am trying to convey to you that there are no shortcuts or free >>> lunches. If >>> > you want to be a master Web applications developer then you will have >>> to >>> > read and learn everything you can about Web development that you can >>> get >>> > your hands on. It is that simple, I am afraid. The benefits are >>> obvious, as >>> > the current limitations you perceive there to be in the GWT documents >>> serve >>> > to exemplify. >>> > >>> > I'm afraid that comparing Google to other companies, even if only for >>> their >>> > quality of documentation, isn't going to be very productive and will >>> just >>> > serve to frustrate you even more. Take the time and go and read, read, >>> read, >>> > and play with all the different things you do read up on. One day soon >>> you >>> > will have what can only be described as an epiphany, that moment when >>> it all >>> > gels and at that moment you will have a big smile on your face - a >>> Kodak >>> > moment! >>> > >>> > Jeff >>> > >>> > On Tue, Dec 7, 2010 at 12:08 PM, Greg Dougherty >>> > <[email protected]>wrote: >>> > >>> > >>> > >>> > > > > If I knew JavaScript and DOM, or, for that matter, even WANTED to >>> know >>> > > > > JavaScript and DOM, I wouldn't be using GWT, I'd be writing the >>> > > > > JavaScript myself. No? >>> > >>> > > > No. >>> > >>> > > > Abstractions do not work for these kind of things. >>> > >>> > > It's not a matter of abstractions, it's a matter of explanations. >>> > > IMAO, the JavaDoc for a KeyPressEvent should tell you exactly what >>> > > that event IS. And what's the difference between it and the other >>> > > Key*Events. It shouldn't be that hard, after all the person writing >>> > > the code had better know the answer to that question, no? >>> > >>> > > Google has detailed requirements for the format of any code submitted >>> > > to be part of GWT. How about a requirement that the documentation >>> > > attached to the code actually has to provide some value, too? >>> > >>> > > And I think you're confusing this post (about trying to figure out >>> > > which event to use) with my other post (where the tutorial code for >>> > > getting an enter key doesn't work). >>> > >>> > > The point of THIS thread is that the people writing "documentation" >>> > > for a lot of the GWT routines seem to assume that everyone using GWT >>> > > spends as much time reading W3C documentation as the doc writers do, >>> > > and as such they end up writing documentation that is worthless until >>> > > you go read the W3C docs (or come here and beg for information). The >>> > > further point is that this is a bad assumption on their part, and >>> that >>> > > it would be good if they stopped writing docs that way. >>> > >>> > > Greg >>> > >>> > > On Dec 4, 6:11 am, Thomas Broyer <[email protected]> wrote: >>> > > > On 3 déc, 20:50, Greg Dougherty <[email protected]> >>> wrote: >>> > >>> > > > > Jeff, >>> > >>> > > > > Thank you. That' lets me know which one I want to use. >>> > >>> > > > > If I knew JavaScript and DOM, or, for that matter, even WANTED to >>> know >>> > > > > JavaScript and DOM, I wouldn't be using GWT, I'd be writing the >>> > > > > JavaScript myself. No? >>> > >>> > > > No. >>> > >>> > > > Abstractions do not work for these kind of things. GWT is no >>> different >>> > > > from jQuery, Prototype.js and others in this respect: it tries to >>> hide >>> > > > browser discrepancies, but that doesn't mean you're freed from >>> knowing >>> > > > them (or least that they exist). >>> > > > What GWT gives you that JavaScript doesn't is that it's Java, i.e. >>> you >>> > > > can reuse some code between your (Java) server and client, you >>> benefit >>> > > > from Java's static typing (which among other things make >>> refactoring >>> > > > efficient), you benefit from the tools from the Java world. >>> > > > (don't put words in my mouth though: there are drawbacks to using >>> Java >>> > > > compared to JavaScript, they're two different languages, each with >>> > > > their own strengths) >>> > >>> > > > > The whole point of using something like GWT is that it lets a >>> Java >>> > > > > programmer write a web app w/o having to learn all the crap that >>> > > > > normal web app writers have to wade through. That's certainly >>> why I >>> > > > > spent the time and effort to learn GWT. For that matter, I >>> presume >>> > > > > that the people writing things like the KeyPressEventHandler DO >>> know >>> > > > > JavaScript and DOM. So, really, how hard is it for them to put >>> that >>> > > > > knowledge into the documentation? Isn't that what the >>> documentation >>> > > > > is THERE for? >>> > >>> > > > The problem is that key/char event is a real mess! >>> > > > All browsers behave differently (though WebKit is really close to >>> IE). >>> > > > Different successive versions of a given browser don't behave the >>> > > > same. The same version of a given browser behave different on >>> > > > different platforms. >>> > > > It's hard (if ever possible!) to build an API with a consistent >>> > > > behavior. >>> > > > See for instance, and amongst many: >>> > > >>> http://code.google.com/p/google-web-toolkit/issues/detail?id=72http:/... >>> > >>> > > -- >>> > > You received this message because you are subscribed to the Google >>> Groups >>> > > "Google Web Toolkit" group. >>> > > To post to this group, send email to >>> [email protected]. >>> > > To unsubscribe from this group, send email to >>> > > [email protected]<google-web-toolkit%[email protected]> >>> <google-web-toolkit%[email protected]<google-web-toolkit%[email protected]> >>> > >>> > > . >>> > > For more options, visit this group at >>> > >http://groups.google.com/group/google-web-toolkit?hl=en. >>> > >>> > -- >>> > *Jeff Schwartz* >>> >>> -- >>> You received this message because you are subscribed to the Google Groups >>> "Google Web Toolkit" group. >>> To post to this group, send email to [email protected] >>> . >>> To unsubscribe from this group, send email to >>> [email protected]<google-web-toolkit%[email protected]> >>> . >>> For more options, visit this group at >>> http://groups.google.com/group/google-web-toolkit?hl=en. >>> >>> >> >> >> -- >> *Jeff Schwartz* >> >> -- >> You received this message because you are subscribed to the Google Groups >> "Google Web Toolkit" group. >> To post to this group, send email to [email protected]. >> To unsubscribe from this group, send email to >> [email protected]<google-web-toolkit%[email protected]> >> . >> For more options, visit this group at >> http://groups.google.com/group/google-web-toolkit?hl=en. >> > > -- > You received this message because you are subscribed to the Google Groups > "Google Web Toolkit" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]<google-web-toolkit%[email protected]> > . > For more options, visit this group at > http://groups.google.com/group/google-web-toolkit?hl=en. > -- You received this message because you are subscribed to the Google Groups "Google Web Toolkit" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/google-web-toolkit?hl=en.
