Dear JavaScript Library Developers…
After spending about three weeks finishing a chapter of the upcoming book introducing JavaScript libraries to non-developers I was quite amazed how tough it is at times to use different libraries.
It was frustrating putting together a set of example scripts for several effects for the oddest reasons, which is why I am now publishing my wishlist for any JavaScript library developers or maintainers. Before you start a new library or expect people to be able to use yours immediately you might want to give these points some thought. For library users this list might be a good “heads up� to see how much work has to go into using a library or how to pick the right library for the job at hand.
Here’s what drove me nuts:
- Lack of offline documentation. I am writing a lot of code on public transport or in hotel rooms where they consider it still an option to charge me for every 10 minutes online. It is not hard to create a PDF or offer a ZIP of the library documentation even if it is Wiki based.
- Lack of step by step instructions and examples for effects and elements of the library. Most of the time you either get no examples at all or a single example that shows all the options you have in one script (or a very complex form to play with all of them – which is only marginally better).
- Lack of unobtrusive examples of code which are those that fall back to working and functioning HTML or HTML+server side script solutions. In the market you will have to develop applications in accordance with accessibility and SEO requirements and both of these require that the page does not rely on JavaScript. It is very easy to create fancy examples that work with JavaScript, but harder to enhance what is already there.
- There is no problem with trying to improve JavaScript or DOM methods in addition to just fixing bugs and browser inconsistencies. However there is a problem if your extensions break conventions like the event model. I have encountered a library that had addEvent() and removeEvent() methods, but no way to stop the default behaviour of the element. This is an oversight that shows me that this library was never meant to be used unobtrusively or to enhance a server side driven application.
- Lack of information about browser support and – even more importantly – fixes and updates for new browsers that might come along. This allows your users to update their library includes or subscribe to feeds that tell them about updates and fixes. As a lot of libraries advertise themselves as a helper to make sure you don’t need to know JavaScript this is the least you should do to gain the trust of users. It is easy to claim everything works, but when there are browser specific bugs you cannot expect library users to fix them inside your library.
- Inconsistency in naming of methods and properties. There is a lot of good documentation on the W3C sites about what an event is, and if you call it action I personally get very confused. If you don’t know JavaScript or the W3C specs that is less of an issue but personally I consider libraries are step towards improving JavaScript and the DOM and not a replacement of them.
- Trying to replace CSS with library methods. There is a reason why CSS is used for look and feel: CSS parsers are very fast and it is great for maintenance to centralise all look and feel in a spot using one technology. CSS is that technology as it was invented for it. Instead of battling CSS, scripting should piggyback on the CSS parser whenever possible (by adding CSS class names to parent elements) instead of changing a lot of style properties directly. CSS has a lot less options to access content and elements than the DOM has and we can use JavaScript to give CSS developers a helping hand to reach these. There is a reason why there are so many “CSS only� solutions out there – people got sick of scanning JavaScripts to find the place to change a look and feel parameter.
- Don’t play the “mine is smaller than yours� card. It gives the wrong impression to new developers as they might be tempted to think that your short wrapper methods are all that has to get executed. We all know that they have to be converted to native JavaScript and DOM methods before execution.
Technorati Tags: JavaScript, JavaScript libraries, comparison, annoyance, rant, webdevtrick, review
December 11th, 2006 at 9:22 pm
"Trying to replace CSS with library methods."
Hear, hear. It's unfortunate that most of these effects functions do not take the printed page into account. By using a class name instead of directly modifying the element styles, we can design a page that looks good and prints properly.
December 12th, 2006 at 11:12 am
"Lack of step by step instructions and examples for effects and elements of the library."
Yeah, this one is frustrating me. Great, I have this library downloaded, now how the heck do I use it? Most of the time its about trawling through blogs finding individual entries, its a pity those entries can't be aggregated or tagged together somewhere. Its not going to be as consistent as a step-by-step guide, but it may be a useful starting point.
Perhaps we need a stack of "Teach yourself DOM Scripting with Dojo in a week" type materials - short developer guides (Teach yourself Abode Spry in four lifetimes?), covering simple workable applications that use and cover core features. Nice niche for ebooks (One I'm considering investing some time to).
An API document is one thing, actually understanding how method calls should be used is another story. JQuery's $() function comes to mind.
December 12th, 2006 at 11:37 am
Chris Heilmann hits a number of pain points in adopting a new JavaScript library. Devel [...]
December 12th, 2006 at 3:38 pm
As a hobbyist in web developpement therefore in javascript (ie : a non developper), I totally agree with this lack of documentation. It is very painful for finding a good documentation for people like me.
Firstly I choose your scripts and read your articles because you have an educational way of thought (ie : from dhtml to dom article) which is very helpful (see also peter paul koch's quirksblog on javascript).
Secondly I choose the articles of alejandro gervasio who published educational articles on devarticles.com. And that man saved my life a numerous times.
For javascript libraries, I prefer to say no at that moment... I believed that this problem was only a french problem but it would seem not.
In short you have two ways :
-1) You explain and show what javascript is and what it is not in a pure theoretical way and you deduce the practical. (The classical french approach).
-2) You explain and show what javascript is and what it is not in a pure practical way and you are able to deduce the theory of javascript. (you, ppk and A. Gervasio)
These two ways meet two different kind of people : professional developpers (the first), non professional developpers (the second).
So thank you for thinking to us :-)
December 12th, 2006 at 10:26 pm
Chris has really hit the nail on the head. Web Development is no longer the field of anyone with a copy of Frontpage and a mouse. Having great libraries makes improving the user experience of the web possible and if you wish to play a part that's awesome. It still doesn't excuse bad practice, or not caring enough to learn about the stuff that's already out there. The people who worked on DOM and Javascript were smart people, and the end result isn't perfect, but that's not a justification to take it all apart.
I really salute Chris, for taking to the time to outline what all Javascript libraries should do. This is just the begininng...
December 13th, 2006 at 8:09 am
Well, all I can think of saying is; amen!
December 13th, 2006 at 10:24 am
“mine is smaller than yours�: Ofcourse size is important. I don't use Dojo because I don't want to add 300kB to a 20kB webpage. That's just silly. I don't want to let my visitors wait 10 seconds for some nice effects. Dojo has it's use in backends, though.
December 13th, 2006 at 4:22 pm
Lack of documentation is definitely the achilles heel of a lot of these geek-approved projects, and not just Javascript libraries!
December 13th, 2006 at 4:40 pm
December 13th, 2006 at 6:12 pm
Posted December 13th, 2006 by John Resig
Some recent articles have discussed the need for having “really good” tutorials for JavaScript [...]
December 13th, 2006 at 8:12 pm
What are "library methods"? I can't find it explained on your site, or others. (It doesn't help that "library methods" are a non-unique search term...) Thanks for elaborating...
December 14th, 2006 at 10:48 am
Charles: a method is a function that is associated with an object. When I talked about "library methods" I meant the functions the library provides you with for example YAHOO.util.Event.addListener() or $('nav').addClass().
December 14th, 2006 at 12:03 pm
I could not agree with you more Chris we need better Libraries not more of the same ole stuff. I think the web becomes twice it's size every year just from duplicate content and I feel fresh unique perspectives are needed I hope to see more free videos in the future for developers looking to learn more about Programming Langauges like Java so more and more people can more widely understand it to use it.
December 14th, 2006 at 2:56 pm
I'd like to second Erwin Heiser's comments -- this isn't just a problem with Javascript libraries. Or rather, it hasn't come about with their advent. It's simply a carry-over from software development. The general consensus seems to be that if something is by geeks, for geeks, then said geeks can figure it out for themselves (and will probably enjoy doing it).
As long as we're on the subject (soapbox, anyone?), whilst I applaud wiki-based documentation if it's the only form available, I think it's an extremely poor substitute for actual documentation written by the developer(s). Why? Wiki-based documentation tends to be reactionary, rather than proactive. In other words, rather than explaining how to use the software/library/etc. and providing details and examples for users to work off of, wiki-based documentation requires someone to run into a problem ("how do I do X?"), and then either figure out the solution for themselves (and take the time to document it) or wait for someone else to do the legwork. Either way, if someone hasn't wanted to do "X" yet, there's generally little-to-no documentation on the subject, even if the software/library/etc. is fully capable of doing it.
December 19th, 2006 at 10:55 pm
December 24th, 2006 at 12:02 am
December 24th, 2006 at 12:02 am
December 29th, 2006 at 5:52 am
January 4th, 2007 at 5:48 am
Editor’s comment: This comment was submitted with a URL of a domain parked porn site as the homepage, I’d be interested how a library had to be customised for that.
Im a developer, back-end and front-end while still making it through to actionscript, javascript, DHTML, dynamic pages to the max, using both the back and front-end to produce static if not user action based functionality, scripts and libraries as they are called here.
Yet, every single script I have used as my starting point/example has had enough to get you just there… Starting. From there you should not hope or wish that any given script will fit your specific need. Instead go into it knowing that you will more than likely have to customize the library every single time you look for or find a new one. Use of these libraries was not meant to make make it a WYSIWYG type situation. You MUST ALWAYS customize any library to fit your interface, ive never used a library in my time that I simply dropped into any of my user interfaces with no input from myself.
So the rant is deaf in my ears, and yes I do work with javascript daily, I do know what it takes to make jazzy stuff melt in your mind and not at your hands…
February 16th, 2007 at 6:38 pm
WoW! Thanks for this very good article … I use this to my home work to school … Can I translate this with all comments and insert on my site? … Thanks
March 20th, 2007 at 6:41 am
"Use of these libraries was not meant to make make it a WYSIWYG type situation."
That's how they're billed: "Our library does all the hard work for you! It's plug and play!" They're not aimed at the sort of people who would be happier writing their own library, they're aimed at the people who would rather not have to do any of that. If you need to reverse-engineer them just to get them to work then they've failed at their objective.
April 5th, 2007 at 12:20 pm
June 5th, 2007 at 3:32 pm
I do agree with the fact that javascript libraries lack of offline documentation, of step by step instructions and examples,and so on..
Besides this, I would like a book which explains the key ideas behind these libraries,that shows how different libraries work out a certain problem, and last but not least how to write your own library!! Does a book like this already exist?......
June 5th, 2007 at 3:50 pm
Chris,why don't you write a book on writing libraries!!!!
June 14th, 2007 at 2:59 pm