Manual Not Included

There is no shortage of bloggers extoling the virtues of Galileo. While the new release builds on the strengths of Ganymede and adds some welcome functionality, it doesn't address the core deficiencies. Namely: documentation, documentation and documentation. (Also: documentation.)

I like Eclipse. My team and I have been building applications with it for over a year, most notably using the Eclipse Rich Client Platform (RCP). I hope that I can make this criticism and also express that I mean no disrespect to those that have put so much time and effort into the release.

That said, without better documentation, most Eclipse projects are not usable.

We've just finished the first iteration of a project using the Google Web Toolkit (GWT) to build a rich web application. After reading blogs and looking through new features of the Galileo release, the Eclipse Rich Ajax Platform (RAP) caught my eye and I decided to investigate it as a possible alternative.

I got nowhere.

There are several interesting demos and screen captures, but none that can even get me started down the road to building a practical product. The getting started page barely gets past installation and while the Wiki does a decent job of explaining the overall architecture, I'm still at a loss for practical information.

Compare this to the documentation for GWT. There is a clean walkthrough for new users. They do a great job of explaining not only what the API does, but why they made certain design decisions. Moreover, they provide more than just an introduction; they provide tutorials that walk users through advanced topics including debugging and deployment.

I can't even find JavaDocs from the RAP site.

Eclipse is a powerful tool. It is necessarily complex - and I've often defended its complexity. But without good roadmaps, the learning curve becomes prohibitive. It took no less than three books and hours upon hours of searching wikis, forums, newsgroups and blogs to get through our first RCP application. It is a scenario that replays itself every time we try to use an Eclipse technology, be it RAP for web applications, Buckminster for builds or GEF for diagramming. Most of the time, we abandon the effort.

We just don't have the time or energy to keep going through that.

If Eclipse wants to be taken seriously - and it deserves to be taken seriously - it needs to focus not on building powerful features, but empowering developers to leverage the platform.