What is it with all these frameworks? Why can't JBoss Seam or even good 'ol Hibernate give me a simple HelloWorld example anymore?

Also have you noticed how complex it is to setup the whole JBoss Seam in the first place?

I am a simple person and Stripes looks much simpler. They also have a HelloWorld or Calculator, an absolutely simple example which you can build upon and play with. Also note how the examples are built without database requirement to setup. It took me about 5 minutes to setup and run the first example. If I were to judge a software solely by its documentation, JBoss Seam fails.

I dabbled with Hibernate before. Now I need to wet my feet again and I remembered an old question. Why in the world did they have to develop a query language like SQL? Why not SQL?

The problem with Seam or Hibernate type documentation is that they are not organized with readers in mind, they don't take the readers step by step into the labyrinth of the mess they have created wonderful software they have created.

Reading each paragraph convinces you that the author was in real hurry, like in the last throes of death, while he was writing these chapters. It makes such chapters almost humanly impossible to understand without feeling absolute disgust and revulsion about software development in general. They make development a chore, a never-ending horror story. Everything and their great-anchestors are crammed into these chapters.

The only purpose they serve is to convince the readers to cough up and buy their books.

Do you know why RoR flourish? Not because they have something great or convoluted. It is because one fine guy has taken the time to create a framework which makes it simpler to develop applications and not make it even more complex than the problem it solves.

Hibernate and Seams team should read RoR and Stripes documentation before they embark on a massive rewrite of their tomes.

Even PHP Manual is a tome but a very readable tome. Tomes don't have to be PITA.

One drawback with Stripes documentation is that it is still minimal. Tag library javadoc doesn't substitute for documentation.

All in all I highly recommend Stripes framework. It solves only half of the puzzle which RoR solves fully. However it does it very well, even better than RoR.
With the other half completed, RoR will finally stop roaring so much :)

To All Framework Authors: Please for the love of whoever you love take the effort to make something simple and elegant. And please spend twice as much time writing documentation which are for human consumption. Please read K&R, PHP Manual etc. to get a hang on writing easy to understand and interesting documents.

BTW: Hibernate with Annotation has a nice thing going, if only they knew how to document clearly.

If there is one thing I really hate about today's java software frameworks, it is their documentation. The bottomline is framework must make our life simpler.

To summarize the points that can be addressed while documenting frameworks are.

  • Start with a simple example; very simple one
  • Say a simple story and carry it through the spectrum of broad capabilities
  • Now delve in the complex details and exceptions and overrides.
  • Stop flaunting your expertise.

In times such as this I head over to bile blog. He knows the pain which most framework developers (with the exception of Stripes and RoR) don't.

Update: An article without an example is bland. So let me illustrate with a simple example from Seam.

The heading of the chapter is: Chapter 2. Seam concepts

The two core concepts in Seam are the notion of a context and the notion of a component. Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context. Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam.

Read it once, twice and then tell me if you understand what they are talking about. To me it reads like incoherent rambling of technical jargon, not a documentation.

First "context" in this context is not defined despite being mentioned. Then they simply include it in a sentence.

"Components are stateful objects, usually EJBs, and an instance of a component is associated with a context, and given a name in that context."

I don't know where to begin. Is it too much to expect a proper and meaningful yet simple sentence?

"Bijection provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing component trees to be dynamically assembled, and reassembled by Seam."

Why wasn't "bijection" introduced earlier? What is the context?
This strange sentence probably makes sense only to a Seams developer.

Are they being penalized to write simple meaningful sentences? Have they read their own documentation ever? Or have their brain become soft working on frameworks so as not to be able to comprehend the problem?
This is merely the tip of iceberg. Such haphazard, poor quality documentation is all throughout.