Working together for standards The Web Standards Project

Chris Heilmann hits a number of pain points in adopting a new JavaScript library. Developers don’t need more JavaScript libraries, we need better quality JavaScript libraries.

One of the big problems of learning a new JavaScript library is the lack of practical step-by-step guides for that library. The API documentation barely scratches the surface of what’s needed. The API is just a dry snapshot taken at a point in time – a roll-call of methods and properties.

A step-by-step developer’s guide should demonstrate the features of the library and show how its methods and properties work together to solve common development problems. What I’m looking for is a book that could be titled: ‘Develop web applications with XYZ library in a weekend’, that contains a series of working examples, using the features of a library as well as explaining those features.

Perhaps its also worth creating a gallery of typical web applications (for example, a blog reader/editor, a calendar, a collapsible tree) and show how these applications are built and developed using the various JavaScript libraries. That gives us a chance to focus on the practical aspects of libraries, as well as identifying and comparing the strengths and weaknesses of libraries.

Chris lists other frustrating pain points including the lack of unobtrusive examples, libraries that break accepted conventions, lack of consistent terminology, and the lack of accurate and realistic evaluation of browser support.

We’ve got a lot of work to do to make JavaScript libraries usable by web developers. It shouldn’t be this painful.

Your Replies

#1 On December 12th, 2006 11:38 am Andy Peatling replied:

I very much agree, all of these libraries are very useful if you know exactly what, where and how to use them.

I’ve looked through and used Mootools lately, which has come on leaps and bounds with its documentation. I still however needed to read posts with useable examples like this in order to get my head around the library a bit more.

For me, the more I can learn from a library being used in real world examples, the better.

#2 On December 12th, 2006 1:11 pm Nicholas C. Zakas replied:

Seems to be a popular theme lately: Why good JavaScript libraries fail.

#3 On December 12th, 2006 3:01 pm Weblog de Brainet S.L » Archivo del weblog » “Queridos desarrolladores de librerías de JavaScript…” replied:

[...] Así es como comienza Christian Heilmann (autor del libro “Beginning JavaScript with DOM Scripting and Ajax: From Novice to Professional (Beginning: from Novice to Professional)“) uno de sus últimas entradas en su blog. Según él, tras estar trabajando en un futuro libro de librerías de JavaScript para no desarrolladores, echa en falta una serie de elementos que servirían para mejorar la utilización de las mismas, o como dicen en el blog de WebStandards, reducir el daño a la hora de utilizar una nueva librería de JavaScript (Reducing the pain of adopting a JavaScript library). [...]

#4 On December 12th, 2006 8:26 pm librarian replied:

There are general problems with the idea of reusable javascript libraries; one is bloat. JS libs should ship with a preprocessor to generate include files that only contain code for the objects and functions in use.

A good example of a javascript library is the google canvas lib for IE. I would hesitate to call it a library, it’s more of a compatability shim and this is why js libraries are popular. Most web developers could throw a library together in a weekend, however we only want to write and debug our code once, not once for every browser.

As for client side javascript frameworks, this a more recent and disturbing trend. Perhaps Tamarin will integrate AOT compilation with browser caching, making these things slightly less rediculous.

#5 On December 12th, 2006 8:57 pm librarian replied:

I should add that I just looked through SVN trunk for mootools as mentioned above. The download of this framework lets you select just the files you need. A step in the right direction but the string class (yes I said class – go see for yourself) contains only a couple of functions I can imagine using. The array class is more useful and the framework is interesting enough to check out.

#6 On December 13th, 2006 12:31 am Rich Manalang replied:

I think most js libraries fail because of sparse or lack of documentation. Documentation, for most, developers seems to be an after thought. However, there are a few libraries that have really good documentation. My favorite is jQuery (http://jquery.com). They just recently posted their API doc on http://gotapi.com. The nice thing about jQuery is that the documentation is built into the development process. You can count on new releases being documented thoroughly.

#7 On December 13th, 2006 12:21 pm Solid Source replied:

Having tried most of the libraries on the market, (having sometimes to switch libraries mid-project – lack of good documentation) I understand the frustrations, very well, of the time and pain it takes to find a good one, so thank you guys from bringing this to print.

6 months ago I was deep in a conversion from prototype/scriptaculous to dojo (for an enterprise app) and found myself again scratching my head at the complexities, lack of solid cross browser support, and pure bloat of dojo. Thats when I found JQuery and after all 10 libraries or variations there of I have tried I will never go back and that is simple because of what this article is addressing. JQuery has a very different approach (the result of which is an easily manipulable DOM), they have loads of documentation (gotapi, as well as existing docs: visualjquery.com, etc), the community is strong, it’s lightweight, and the effects, plugins, AJAX support are second to none.

Not that I want to plug one particular library but I think JQuery illustrates the solutions to the above points/problems better than the rest. Hopefully this article raises a bit of awareness to all of the soon to be lib developers out there that simply putting together another API is not what the development world needs now.

#8 On December 13th, 2006 1:12 pm jQuery: Blog: » Helping you understand jQuery replied:

[...] Some recent articles have discussed the need for having “really good” tutorials for JavaScript libraries. [...]

#9 On December 13th, 2006 1:12 pm Jake replied:

When I went to choose a library, I downloaded some pages and the entire library. Some were horrible, full of modifications to the dom and non-valid xhtml or almost as many lines of code as the low level calls. But I kept on reading. Then I found jquery. at first look I thought ‘what language is this’, ‘it looks like some lambda influenced language, some son of a lisp…. upon further reading, I realized it’s just javascript…. and I understood most of the ways it was done. The code is brief, and the code you write is almost lyrical!

Where else can I say something like this:

$(“#footer”)
.width(“100%”)
.addDir({dir:”Pix/Friends/”,width:30,randomize:true})
.addDir({dir:”Pix/HD/”,width:50,randomize:true})
.addDir({dir:”Pix/Family/”,width:30,randomize:true})

with one little function addDir that is only a dozen lines of code?

Where else can I ask a panel of experts about the simple and mundane or the complex and intricate effects or ajax?

Amazing code + amazing people = success.

#10 On December 14th, 2006 4:37 am Chris Heilmann replied:

John Resig of jQuery has asked people on the jQuery blog to give examples of what tutorials are needed, and this is a great step ahead.

As to the comments here, please stop advertising one or the other library and their code, this is not the point of this. Especially the last code example by jake is an exact violation of the idea that you should leave CSS to the CSS parser and you shouldn’t create scripts that make functionality dependent on JavaScript. Just because you _can_ create a footer with JavaScript it doesn’t make it a good idea.

#11 On December 14th, 2006 9:43 pm links for 2006-12-13 at found_drama replied:

[...] Reducing the pain of adopting a JavaScript library via The Web Standards Project (tags: webdev javascript essay todo) [...]

#12 On December 16th, 2006 8:33 am David A. G. Dávila Zambrano replied:

I got your page learning about HTML because I am needing reach upgrade to my personal position.
All about W3C to me is as a new horizon, when i was to school the comptutacion was not existent and Java L.
Is something like the order all in this planet are nedding.
G. bless all you

#13 On December 18th, 2006 5:43 pm Joseph Morphy replied:

Perhaps the best JavaScript framework/library is Prototype. Probably its only drawback is lack of great documentation. It isn’t so much of a problem anymore, though.

Post a Reply

Comments are closed.