If you’ve ever spent anytime using Hibernate, you can most likely appreciate the time the folks on that project have spent putting their documentation together. In my opinion, the Hibernate folks have created one of the most complete sets of documentation for an open source project I have come across to date. In some cases, these docs surpass the quality and detail than some commercial products. Not only that, but the Hibernate wiki is also and invaluable resource, the community contributions are generally of very high quality and complement the base documentation nicely. For any project or product to succeed these days good documentation is key.

Even Sun has understood this, and has provided us with the excellent Java tutorial, Swing tutorial, J2EE tutorial, and numerous others. Personally, I have found Sun’s tutorials to be an invaluable resource in the past and I appreciate the effort put into them. What baffles me however, is the documentation for the Jini project. What the hell happened here? Jini is a really cool technology, to grasp Jini concepts and get started creating Jini services.

When I got a hold of the Jini starter kit, I was expecting to find not only Java docs, but also some sort of documentation on how to create and run a real-world Jini application. I was expecting to come accress some sort of tutorial describing how to create a Jini service and how one might be able to use Jini in a real-world application. You know, something similar in terms of the J2EE tutorials. If you’re looking for that sort of thing, you’re shit out of luck. Instead, you get a several pages of documentation on how to run things like “fiddle” and “reggie” with the example applications along with the full Jini specification. There is also extensive documentation on how to secure a Jini application, which is great considering what’s going on with Jini. But there is absolutely nothing (or at least anything useful anyway) on how you can create your own Jini service. Sure there is example code, but without docs describing what the example code does how useful can example code be?

Sun recently changed the licensing for Jini with version 2.0 to the Apache 2.0 license in an effort to spur adoption by developers. While this move does remove several barriers to wider adoption, it still doesn’t help the fact that most folks still don’t know what Jini does. The description on Jini.org is such marketoid drivel; it doesn’t convey to the average developer what Jini can do for them. And those who do know what Jini is capable of and what it’s for, it’s still very difficult understand how to make Jini do its thing.

As a Jini noob, here’s what I’d like future Jini docs to touch on:

• Give us a real explanation of what Jini is, not a bunch of marketing babble.
• Show us a good, simple sample Jini app and explain what each component is doing.
• What JARs need to be present in a Jini Application?

Jini is cool if you take the time to scour the web to find out what Jini actually does. Adoption of Jini will be slow unless Jini,org can provide all of this information in a single source.