The power that Hibernate provides is both compelling and elusive: It's
clearly a better solution than using CMP. It seems to be very commonly used
with EJB session beans by users in the real world. But it's elusive in that
the gotchas are not well documented, and the documentation rarely states
things more than once. Getting "over the hump" with it is more difficult
than it needs to be for such a mature product.
Have you checked out: http://hibernate.bluemars.net/5.html
There is about 10-15 links to seperate documentation documentations/sites.
Besides the primary docs (which attempt to be precise and concise): http://hibernate.bluemars.net/hib_docs/reference/html/
A quick tutorial: http://hibernate.bluemars.net/hib_docs/examples/
Community area with gold nuggets! http://hibernate.bluemars.net/37.html
And even external doc links too ;) http://hibernate.bluemars.net/78.html
I know that the "hard core" part is hard to get at, but I think
that is true for any software project - no matter how well it
is documented - users/readers always have a certain "offset" in respect
to what the documentation states and what the users think.
(example: I can't count how many times we have been asked if Hibernate can be provided a custom-opened connection, if it support joined table inheritance, single table inheritance, if the QL supports join, if the ... etc. etc. and guess what - it is all there in the docs, even with
word-by-word headlines ;)
For instance, it just occurred to me that there must be a test package. I realized this as I was about to list that there was very little sample code in the example package (the "eg" package). So I looked and there was the test package, all 120+ files of it. Zero doco, but 120 files nonetheless.
"eg" is a very simple test - check out the other example apps/docs referred to from the links above.
From this example alone, some packaging roadmap (minimally in the form of a package.html files in the javadoc) would be a huge help. In any open source project, the source itself is the best documentation, but there are 600 or so files in there that don't have much in the way of explanation of key architectural concepts. I know that the patterns in there are painfully obvious to you guys because you grew it from a little seed. These things can be hard to document because the forest and the trees start to look like one. And someone that is able to finally write the doc, they are suddenly more interested in getting some action in CVS instead of writing doco. I know what it's like... and there's really no ground for complaints because I would do the same thing!!
See, know we are talking ;) This is the more technical docs about the core and private internal api's, right ? Here everything could be better , and I also think this will approve over time now that we are getting a more and more mature codebase that is worth documenting ;)
Maybe there is some focus that you guys could do for documentation.
Something's gotta be done.
We have this focus - and we document anything we find a current need for.
In my view (i know that i'm a bit naive ;) the best way/chance for this docs to be written is that someone ask the question: "How does Hibernate realize this issue X ?" and it will in some way be explained by someone at the hibernate team (and maybe even documented) - and if it is very technical we often point users to the code for further explanation....and guess what - now that user has all the possibilities to write the docs (and we will be happy to comment and correct anything that might be wrong) and even put it on the wiki - see this the really true power of open source and an active community and developer team as Hibernate is a good example of ;)
I hope the criticism comes off as constructive, I write this with only good feelings for the project and appreciation for the efforts you guys have made.
I dig it! And I follow - but I also would like you (and anyone else) to drive the need for documentation in the same way new features and bugfixes are driven by users: By user requests and patches!
Best regards, Max
------------------------------------------------------- This SF.net email is sponsored by: VM Ware With VMware you can run multiple operating systems on a single machine. WITHOUT REBOOTING! Mix Linux / Windows / Novell virtual machines at the same time. Free trial click here:http://www.vmware.com/wl/offer/358/0 _______________________________________________ hibernate-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/hibernate-devel
