Too many libraries, not enough librarians

Christian wrote recently about his frustrations with JavaScript libraries. Most of his complaints—and those in the comments (mysteriously hidden via JavaScript from Safari users fixed!)—revolve around the lack of decent documentation. This is a really important point that Mike Davies echoes on the WaSP’s DOM Scripting Task Force blog:

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.

In response, John Resig has put out the call for good tutorials for jQuery, which is a very welcome development.

The accepted wisdom seems to be that everyone is going to use a JavaScript library so it’s important to find one that works well and is well documented. But I was listening again recently to the recording of the excellent @media panel, JavaScript Libraries: Friend or Foe? and I was reminded of the surprising results of the quick audience poll: half of the people using JavaScript weren’t using any library whatsoever.

There’s a lot of talk about JavaScript libraries, including a lot of hype and cheerleading, but I think that maybe the discussion is disproportionate to the amount of people actually using libraries. Personally, I’m somewhat mistrustful of using other people’s code (I’m a bit of a control freak) and I thought I was in the minority, but having spoken to people like Stuart and PPK who share my feelings, now I’m not so sure.

In any case, even if libraries aren’t quite as widely-used as we think, there’s still a definite need for good clear documentation.

Posted by Jeremy on Thursday, December 14th, 2006 at 4:09pm

Comments

I think one issue with your census is that you’re going against a very biased user base. The type of people who would attend @media are established web designers/developers. This means that they’ve been "around the block" a few times, have used JavaScript, and know a good number of the browser bugs that exist. Therefore, they’re less likely to be inclined to use (or have the need for) a JavaScript library.

This is not the case for people just starting web development (anyone who started after early 2005, when good JavaScript libraries first started appearing).

I’d break down the percentages like so: * Hardcore JavaScripters (like PPK and Stuart): 10% use libraries * Long-time Web Developers: 50% use libraries * New (post-2005) Web Developers: 80% use libraries

I’m finding this to be true, from experience. Although, having some real numbers would be awesome. Remember: What’s good for PPK, isn’t necessarily good for everyone who isn’t PPK.

# Posted by John Resig on Thursday, December 14th, 2006 at 5:33pm

I love the attempt that Beauty in Design is doing with screencast about MooTools called "Free Series! - MooTools for the Rest of Us". That is truley something to start with.

The only thing that’s missing is a API documentation about Prototype.

# Posted by G.Lindqvist on Thursday, December 14th, 2006 at 5:50pm

I am using jQuery on regular basis, and I find JavaScript libraries very handy and efficient way of coding. I’ve also listened to the podcast you’ve mentioned. There is one important point one of the speakers is making - if you are PPK or Stuart Langridge you can do very well without any libraries whatsoever. However, if you are a not a JavaScript developer with a lot of experience, who just want to code something fast and easily, that will work in different browsers straight away, JS libraries are the best option in my opinion. After all, we (me at least) do not build sophisticated rich web applications everyday. Fading away a box, fetching something simple via AJAX - that’s what I have to deal on regular basis, not another GMail application requiring fully optimized and well thought over code.

# Posted by Krzysztof Danek on Thursday, December 14th, 2006 at 6:34pm

I’m using libraries, they do a lot of work for you. But I can’t say what is the better choise.

# Posted by JaViS on Thursday, December 14th, 2006 at 9:49pm

Though I recognise the obvious benefits of using libraries I also see pitfalls; I think their use removes much of the incentive for non-Javascript fluent users to truly master the core language itself. Personally I never used them.

# Posted by Steve Tucker on Thursday, December 14th, 2006 at 10:26pm

The way I see it: if you want people to use your library, you’ll need to give them an "interface" to that library.

The code itself is not the interface. The documentation is.

A short description of all the possibilities will allow users to decide whether it’s worth their time (and money?)

An in-depth description of the library itself (containing loads of examples) will make it easy for them to use it.

If users "get" it, they’ll use it.

# Posted by Michael on Friday, December 15th, 2006 at 9:21am

I use YUI exclusively for most of my javascript work. Anything more complex than simple event attachment, and I prefer using the library. However, using a generic library often brings in performance issues because the developer of the library could not make assumptions about how it would be used.

As Eric[1] once said to me when I brought this up, "you choose your battles". There are some applications where I write my own code, for example, to replace YUI’s getElementsByClassName with a faster, but less generic version[2].

[1] http://blog.360.yahoo.com/ericmiraglia

[2] http://bluesmoon.blogspot.com/2006/06/yui-addlistenerbyclassname.html

# Posted by Philip on Sunday, December 17th, 2006 at 2:37pm

I download and experiment with js libraries all the time but find them more trouble than they are worth. It just seems easier to do the job myself (and learn about JavaScript itself) than wade through someone else’s wrapper for scripted features.

This is definitely not true for the Java and .Net programmers I work with. Not comfortable with JavaScript —and seduced by the object-oriented syntax of many of the libraries— they tend to favor libraries. But after getting hooked, they end up bouncing from one library to the next, searching for some feature that the current silver bullet does not have. Or they encounter some problem with the library and if they don’t feel competent with JavaScript, they certainly are in no position to modify these libraries, which are often pretty advanced stuff.

Many JS libaries are over-engineered playthings. I am not attracted to complexity. Until I find a library that simplifies my development tasks, I will stick to what I am doing.

# Posted by Brett Merkey on Saturday, December 23rd, 2006 at 9:57pm

I am a latecomer to the JavaScript party—unfashionably late, I’m sure—and only started to get excited about it and see its potential while reading your excellent book, DOM Scripting. As a CSS zealot, I immediately resonated with the ideas you discuss of unobtrusiveness, progressive enhancement, and graceful degradation. Separation of behavior from content was not a stretch for someone like me who was already espousing separation of presentation and content.

Soon after applying a number of the techniques in your book, I was seduced by the Lightbox script, which uses Prototype/scriptaculous, and I implemented it on a couple sites. But it bothered me that so much code was needed for such a small effect, and the more I looked at the Prototype examples, the more they seemed (without behaviour.js) antithetical the ideals of your book.

That’s when I discovered jQuery, the compact JavaScript library created by John Resig. Everything about it made sense to me, from the CSS selector expressions to the intuitive event handling — all of which could be done in a separate JavaScript file.

Back in June when I first started using jQuery, the documentation was, admittedly, pretty limited. But that has changed quite a bit in the months since then. Not only has the API really taken shape, but the site’s explanations and examples have become more numerous, more detailed, and more useful. The jQuery discussion list has also been an invaluable source of information about some of the finer points of the library.

As for me, I wholeheartedly agree with the need for even better documentation, more tutorials, and more accessible examples. That’s why I started the Learning jQuery blog in September. Rather than stunting my JavaScript development, jQuery has helped me to understand much more about what JavaScript can do and how. It has also helped me become a better, more efficient, more responsible web developer.

I don’t know enough about the other libraries to comment on them, since I haven’t been "bouncing from one library to the next," but I can say that (in my experience, at least) jQuery works as an excellent complement to DOM scripting.

# Posted by Karl Swedberg on Wednesday, December 27th, 2006 at 6:34pm

The Tennaxia OpenSource Unobtrusive JavaScript Framework @ https://www.tennaxia.net/tos_trac/ contains

# Posted by Maxime Delorme on Friday, January 12th, 2007 at 7:05am

Thanks, Maxime: that’s the perfect example of how not to document a library.

# Posted by Jeremy Keith on Friday, January 12th, 2007 at 9:47am

Sorry. Comments are closed.

December 2006
SunMonTueWedThuFriSat
     12
3456789
10111213141516
17181920212223
24252627282930
31      

Recommended Reading

XML Subscribe

Grab the RSS feed for this blog.

JavaScript API

Grab the RSS feed of comments for this entry.