Firstly, and most obviously, for any software framework to become mainstream it has to be good. Ignoring what good means, what else does it take? Good documentation! Right now in the Ajax world there are many frameworks coming out trying to be the “one” main framework. The problem is that although several are really good, there’s virtually no documentation for any of them. Talk about a great opportunity to take over a market.

For example, today I was looking at the Dojo toolkit. It looks very promising. It can do some amazing stuff. But there’s virtually no documentation. The only documentation that’s available is for the older version (which is significantly different), and even that’s very sparse. The only documentation is the code examples. Problem is that Javascript is not a strongly typed programming language, and nor is there really a great IDE solution that lets you work with it. So you end up having to go back to the “old school” way of learning code. Opening files one at a time, trying to figure out where a variable was defined, what type it is, what it really does. This is extremely tedious, frustrating, and especially time consuming. But worse than that, it makes for a very high learning curve since some of these frameworks are pretty large and complex.

And Dojo isn’t the only guilty framework here. Open-jACOB is another one that looked really promising (especially Draw2D) but it was next to impossible to figure out. The demos are amazing. Good luck figuring them out though. The list goes on. Even Ext-JS which currently has the best documentation among all of them is mediocre documentation at best. What saves them is their forum. But having the forum be a main source of documentation is not a good solution. A lot of time is lost trying to find the relevant threads, and then finding the right answer.

If you look at the Java world, everyone is familiar with Struts. Back in the day Struts was the main J2EE framework to develop by. It was decent framework for its era. Whether or not it was the best is debatable, but it was popular because figure out how to use it. It had good documentation. They did a good job of documenting it. It can always be better but they at least brought it to a point where you weren’t always frustrated trying to figure out how to do the next thing. The latest Spring and MyFaces frameworks are also experiencing success for similar reasons.

It takes more than just being a good framework to become mainstream. Above being easy to learn and use, it also has to be well documented. I remember back in the day looking at alternative frameworks to Struts (when it was the new kid on the block) and getting frustrated. Although today I no longer use Struts, it did have its moment in the sun. And I personally believe one of the main reasons it did became so famous was because of its documentation. If you can’t figure it out odds are you won’t use it.

So my quick tip of the day: if you’re one of the several new Ajax frameworks vying to dominate the market look at improving your documentation sooner than later. Many of you have amazing features but if we can’t figure out how to implement them, then we just won’t. I know that if one of the frameworks I played with today was easy to learn and properly documented, odds are very high I would have gone with it, even if it wasn’t complete! There’s a great opportunity here, nows your chance to seize it.

Discuss (2)