I'm putting a serious effort into understanding Hibernate, but sometimes I just have to sit back and say.. WTF? One of these comes from this line:

TODO: put words around this stuff

you can find that here: http://www.hibernate.org/hib_docs/refer ... pings.html

I understand Hibernate has some serious intentions and is used in many, many database heavy applications. Still, I can't help but wonder... Is this Hibernate documentation just an afterthought? If there are TODOs still in the docs, what else is missing? Are the numerous typos a feature? Are grammatical inconsistencies "persisted" to confuse hibernate noobs such as myself?

Sure, I could probably file a bug because the word no was used instead of the word not, or a certain TODO has been there for a year already. But hey, I'm only Yet Another Programmer who's just trying to understand Hibernate so that I use it correctly. And what can I say, it's only documentation, right? I'm sure my docs aren't any better.

But then, my docs aren't read and referenced by the world at large! (yet?) Someday, if the world does read my docs, I hope some dickhead like me comes along and points out the silliness of having TODOs spreckled throughout the documentation.

I know some of you are Slashdotters who wouldn't hesitate to point out a grammatical error in someone's Insightful post, and I'm sure some of you may point out some foolish errors of my own. Take some of this English angst and please update your documentation!

And yes, I signed up today just to complain about the docs.


TODO: put words around this stuff
wow....

Everyone feels your pain.

Everything has to get prioritized, and unfortunately, documentation often gets put towards the bottom of the list. And for that matter, some of the people that know the documentation the best are often fixing bugs or adding features that are highly in demand, which is probably where the Hibernate community of developers really wants them. Then you get 'lesser' developers afraid to update the documentation, lest the actually put something wrong in there, which would really, really mess things up. It's a vicious circle, but it's the way it is.

Sometimes we take the good with the bad. For the most part, I think the good far outweighs the bad, and where it's bad, I keep faith that it will get better. It usually does.