I keep a copy of the full 133 page-long NHibernate docs .html saved on my desktop at all times :)

NHForge.org seems to have a woefully poor Google pagerank.

I suspect some people don't know it exists.

This will be a very helptful post to many people as it will be ranked high in the SERPs so many will find it.

However people do not complain without reason. The documentation might be there and might be good (in my opinion it is) but apparently it cannot be found easily or it is not easily digestable. You can say that this is not the problem of the NHibernate community because if people are so stupid they dont deserve it and so on. This might be true but it is still your problem, too! That is assuming you want adoption of NHibernate.

Think about a product company selling food. Even if the food is superior to every other product it must be marketed well because otherwise nobody will buy it. As a manager you cannot say: The people are stupid because they should inform themselfes. It is your problem too.

So you should ask yourself, why are the people really complaining? How can we satisfy them?

Just out of curiosity, how come that nhibernate.org always lags so much behind. It lists the previous version, it lists ages old documentation. And if one googles for NHibernate, the website nhforge.org is nowhere to be found on the first page.

It would be great for people which are new to NHibernate, if nhibernate.org would not show any information at all and just link to nhforge.org.

well, I don't want to sound harsh but the book is anything but __excellent

most of the time I stand on the NH side but sometimes I wonder if this all happening in the last week hasn't gone too far.

I would say it is the __only book avaiable for NH, I would paraphrase statement as good book to get when you don't have much time reading blogs/articles/guides spread all over the net and NH is a new word for you. But it could be definitely better, much better.

Amazon review, there's not a point bashing on this book (there's few other negative comments) as NH 2.0 doesn't differ much from 1.2 (2.1, LINQ, fluentNH etc is another matter), my point goes to a "war" in the recent days that tries to put NH on a pedestal of kings.

__
Most of the text in this book is copied from Hibernate in Action, a best-seller in 2004, except some C#2005 example code for an old NHibernate release - NHibernate 1.2, the equivalent dotNET version of Java Hibernate 2.1 covered by Hibernate in Action.

The current NHibernate release is 2.0, which had been released for six months before this book was published.

And the revised edition of Hibernate in Action, Java Persistence with Hibernate (covering Hibernate 3.2), was published in November 2006, two years and three months before this book.

amazon.com review

cowgaR,

There is one thing that the books excels in, it gives you understand on how NHibernate operates.

As for the rest of it, putting a book out takes a LOT of time an effort. Probably more than you immediately realize.

Ayende,

Is this post is response to suggestion at nhprof.uservoice.com/.../292473-write-nhibernat...

Giorgi,

Actually, no :-)

I can also highly recommend Steve Bohlens SummerOfNhibernate Screencast series:

http://www.summerofnhibernate.com/

It is 15 Screencasts showing you hands-on NHibernate

The documentation is good. However, it doesn't stay very up to date with the features. I find your blog is more up to date on new features than the documentation is.

The problem I have with NHibernate's documentation is simple: accessibility. You go to Google, search for NHibernate and it takes you to Hibernate's website (which, quite frankly, is terrible). This site, in turn, links to an older version of NHibernate, and worst of all, links to documentation for v1.2.0!

The documentation that exists is fine. Finding it is the problem. That really really needs to be fixed.

There you go again Ayende in your response to cowgaR.

He makes a perfectly valid statement and you stand firm on your retarded statement.

You're just so narrow minded you dont accept any position except your own.

close minded,

Interesting, I don't get to have an opinion?

Or disagree with people?

Not to add fuel to the fire, but anonymous comments like the above are reasons that I stopped blogging

I'm not a user of NH, but I've had a similar experience to what some others here have stated with open source frameworks--searching for the docs via google often leads to finding an old version of the docs.

I have had this problem in the past with Rhinomocks (which I love BTW), and Structruremap.

There's a lot of well written and explanatory documentation about "Hibernate". I've found you can extrapolate a fair amount about NHibernate by reading the books and just mentally filtering out the Java parts (JARs/Classpath/etc). Though that really only takes you so far. Unfortunately I started with the abysmal NHibernate book which was such a poor intro that I wrote NHibernate off for awhile and wasted a couple of months on EF before I decided to give NHibernate another go.

What would actually be handy is seeing a reference implementation of a project, or picking through a list of some successful open source projects that use NHibernate. Ayende - I think that that NHibernate version of Nerd Dinner you promised would go a long way towards giving people a useful 101 tutorial on using NHibernate. Any ETA on that?

"What would actually be handy is seeing a reference implementation of a project, or picking through a list of some successful open source projects that use NHibernate"

I would love to see a fully working reference implementation.

Unfortunate, I have to use a CHM as I rather would have used integrated documentation for the Microsoft Document Explorer. NHibernate 1.0.2 was the only version which released such version. Why is Visual Studio integrated documentation dropped?

I don't really want to bash the volunteer efforts going in to maintaining the NHForge docs, but the introduction seems a bit outdated:

"This tutorial explains a setup of NHibernate 1.0.2 within a Microsoft environment. The tools used in this tutorial are:

[...]

Microsoft Visual Studio .NET 2003 - the development environment. "

In fact I don't think NH 2.0.1 even supports VS 2003 :)

I'm sure the relevant parts of the docs are up to date, but for someone that reads it for the first time it's not the best start...

You are correct in that NHibernate has tons of documentation, but the documentation needs to be updated. As Eirk mentions, the introduction and configuration is still specific to NHibernate 1.0.2.

5..4.1. generator took me a while to figure out how to correctly declare a foreign key constraint on an identity key generated in the parent table. We're working with legacy databases that implement tons of one-to-one relationships based on identity keys.

It turns out the correct syntax (not documented anywhere that I could find) is:

<generator
<paramNameOfParentProperty

Without that, NHibernate threw an exception saying it expected an element named property. I finally found a reference to foreign key generator on another site.

5.1.9 property can be specified as generated on insert but I haven't been able to figure out how to get NHibernate to associate a generated property value into a key of a child table. In this case, the legacy database has a few tables with incredibly stupid relationships; e.g. Parent->ChildA, Parent+Child->SubChild in which Parent has an identity key, ChildA has ParentId plus a separate identity key, and SubChild has both ParentId and ChildId. No, it isn't pretty but I can't modify the schema to fix it.

I think the mapping section rolls through everything a little too quickly without really explaining the relationships between the domain classes and the tables; specifically, when to include the parent entity and/or indexer property in the child isn't clear. For this, I've been merging in your explanations into the NHibernate docs to help clarify.

I have both the book and the documentation (thanks to someone in the comments of a previous post pointing out that the docs on nhforge have been updated). While the book IS a good introduction to NHibernate, I have found it to be a little light on details compared to its Java counterpart. Don't take that as an insult though, just that given it IS the only book on NHibernate, when I purchased it I had hoped for a little more detail and better coverage of advanced topics.

Now, the docs do a good job of filling in the gaps, but up into a week or two ago I had no idea there were updated docs on the NHForge site.

Just a hopeful suggestion for someone who's a big fan of NHibernate - could you convince the JBoss guys to redirect the old, outdated NHibernate docs on the Hibernate.org site to the new docs on the NHForge site, perhaps even the entire NHibernate section on the Hibernate.org site as well? This would go a long way to clear up the disparity in people's minds when they're looking for those extra details they can't get from the book.

One quick example - the book mentions nothing about many-to-many joins, I had to find the answer for how to achieve this by searching on Google, digging through results, and finally finding a blog post that talked about it. I underestimated the "magic" that goes on under the covers in HQL :)

That's too bad! At least you guys tried.

Perhaps a request to the community is in order for a concerted effort to back-link and convince Google that NHForge is the authoritative site for NH docs? I know I'll be linking to it, though my blog is a pitiful little corner that only I really visit :)

There is also the Summer of NH screen cast series:

http://www.summerofnhibernate.com/

Ayende: I brought up the second issue on the NHibernate Users forum but I haven't received any replies since posting there a couple weeks ago. I was working on a fairly complex project to merge several legacy VB6 applications and a ton of stored procs into more of a domain-driven design with NHibernate. Unfortunately, mapping that complex relationship was critical to the project and I was on a deadline, so I dropped back to using ADO.NET instead. I still have the original mappings and want to revisit the project in the near future if NHibernate can support propagating generated property values into child classes.