I have found many times over that the Hibernate user manual and Javadoc, while excellent, are unclear or incomplete. I can most often find an answer in the community area or the forums, but it would sure be nice if all that knowledge and all those tips got rolled up into the official docs.

What is the best way we users can help the Hibernate development team improve the quality of the documentation?

• Just continue to rely on these Forums,
• Post content to the Community wiki
• Submit issues to JIRA (I assume this is not an intended use)
• Other?

Post on the wiki, help to clean the wiki and complete the existing pages, help with the translation. There are many beginner tutorials now from many people, so thats fine. Help with the complex scenarios, like EJB and rich clients.

The reference documentation has already been cleaned up, this update will be included in the next release. Also keep in mind that it is a reference, not a tutorial, not a "i'll help you learn reading" and not a "everyone understands everything after reading it once" type of book. It is a reference, it lists all features with a short explanation. The updated version will have an improved TOC, but I still think that the content is very good and we should not bloat it.

I think focused how-to guides, tutorials, and the like make for excellent companions to the user manual -- and agree that no good would come of throwing everything together.

I'll start adding to/cleaning the wiki and see where that leads. No need to have an debate in the abstract about what should (not) go into the docs ;>

I cannot help with translation, sorry, unless you want 2nd grade level French in the docs.

Definitely.



Excellent! Thanks :)