I agree... I'd argue that no matter how many cool features the "next version" of jQuery has, if the docs and underlying support mechanisms aren't intuitive and easy to use, then people will turn away from it. I think that the next "release" should be full-featured, robust documentation. andy
_____ From: jquery-en@googlegroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Rick Faircloth Sent: Friday, September 28, 2007 8:59 AM To: jquery-en@googlegroups.com Subject: [jQuery] Re: When will the API be updated for 1.2.1? <soapbox> I've been saying for awhile now that jQuery, now that it is becoming more popular, with even more new users and developers of plug-ins on top of the rapidly developing core, needs a content management system to handle, in a systematic, disciplined way, the core updates, plug-in availability as well as compatibility, and all associated documentation. The reason given, and it is understandable, is that this is a loosely connected, volunteer effort on everyone's part and expectations and discipline can't be enforced on volunteers. I disagree. If everyone wants to see jQuery continue to prosper, it, and those associated with it. core developers, plug-in developers, and users, will have to work within a disciplined system to maintain usability. It's getting out of hand. I would love to try the new image shadow effect in the latest core, but I'm afraid to put the core on a page with jQuery that is running well to see what happens. If it doesn't work, then there are endless hours spent trying to track down fixes, or find out answers to compatibility questions, documentation, etc. At some point, the chaos will turn users away from even a superior form of development. And can a poorly supported system of developing, meaning it lacks disciplined development, testing, and documentation, even be called superior? </soapbox> Rick From: jquery-en@googlegroups.com [mailto:[EMAIL PROTECTED] On Behalf Of Juha Suni SC Sent: Friday, September 28, 2007 9:24 AM To: jquery-en@googlegroups.com Subject: [jQuery] Re: When will the API be updated for 1.2.1? In the meanwhile it would help tremendously if the documentation and API links were consistent in where they point to, and the 1.2 api in the wiki was easy to find. FYI: The 1.2 API in the wiki is at: http://docs.jquery.com/Core (or by clicking "jQuery Core" in the wiki main page at http://docs.jquery.com) Problems: Most documentation main page links point to the 1.1.2 -version API. For example clicking "Attributes" on the main page (http://docs.jquery.com) under the DOM in the right, takes you to 1.1.2 API. As do all the other under the DOM-title. "Traversing" for example takes you to http://docs.jquery.com/DOM/Traversing which is 1.1.2, but to get to the 1.2 traversing-section you need to click "jQuery Core" first, then choose traversing from the left to get to http://docs.jquery.com/Traversing which is 1.2. This is made even more difficult by the fact that all the API-links you find in Google and in jQuery-related discussions point to different places, none of them being 1.2 or even having a link to 1.2 or even mentioning they might be out of date. http://docs.jquery.com/Api again has links pointing both to 1.2 and 1.1.2 docs nicely mixed together. The "official" (it is, right?) API on the other hand is only 1.1.2 with no mention of it being outdated. Same goes with the visualjquery.com -site which is certainly very popular and many links point to it. This is extremely confusing for new users, and even for us regulars. I spent 10 minutes trying to find the 1.2 API that I remembered stumbling upon before. Many new users might have no idea they are browsing an old version of the API (its easy to confuse 1.2 with 1.1.2). This is made even more important by the fact that 1.2 and 1.1.2 actually do have major differences and some 1.1.2 stuff just won't work under 1.2. One of jQuery's key strengths is the low learning curve and good documentation. With outdated documentation (especially when up-to-date documentation _is_ available) making things harder for new users these benefits disappear. I'm certainly not trying to bash anyone and I do understand the possible difficulties in getting things to work smoothly and in keeping docs up to date. I'm just suggesting that since we do have a decent up-to-date API at http://docs.jquery.com/Core, shouldn't most links point to that instead of the outdated 1.1.2? And even though the 1.1.2 API would still be available, I'd strongly suggest placing a visible text informing the user that the information might be outdated with a link to the latest API. ----- Original Message ----- From: Brandon <mailto:[EMAIL PROTECTED]> Aaron To: jquery-en@googlegroups.com Sent: Thursday, September 27, 2007 6:24 PM Subject: [jQuery] Re: When will the API be updated for 1.2.1? The documentation is going through some growing pains. Currently the only source of documentation for 1.2.x is on the wiki. I've been thinking about how we can take those docs and create an XML file like we had before ... currently the only idea I have is to screen scrape which if you look at the actual markup of the Wiki is a pain and doesn't scale well for inclusion of plugins, etc. I've made a little progress (still have a long way to go) with using Hpricot to at least get the core docs into XML. -- Brandon Aaron On 9/27/07, Andy Matthews <[EMAIL PROTECTED]> wrote: I use this: http://jquery.com/api/ all the time because it's the simplest, easiest, reference for jQuery methods and behaviours. But it still lists it's version as 1.1.2. Are there plans to update this reference? Alternately, I'd argue that there needs to be ONE single point of entry (on the jQuery site at least) for a straight up reference. I'm not talking about the fluffy examples found in the wiki area, but just a terse explanation of the method, it's parameters, and how to use it. ____________________________________ Andy Matthews Senior ColdFusion Developer Office: 877.707.5467 x747 Direct: 615.627.9747 Fax: 615.467.6249 [EMAIL PROTECTED] www.dealerskins.com <http://www.dealerskins.com/>
<<image001.png>>
