What you would like to have in our reference documentation

[Fabio Maulo]

Consider this thread as a poll to know what you would like to have in our reference documentation.

We know that we have some obsolete info, some incomplete info and a lot of info spanned in various blog posts.

What you would like to have in our reference documentation ?

more images ?

step by step example about some general mapping task ?

specific "How to" ? about what ?

more details about extensions points ? which one ?

....

....

....

Please collaborate with some ideas and will try to find a solution.

We will use this thread to find better ideas and apply it.

Thanks.
--
Fabio Maulo

P.S. try to avoid to transform this thread in personal discussion, each one has an opinion and opinions, in this case ( ;-) ), are welcome.

[Matthijs ter Woord]

I personally feel there should be a short description of what a
method/class does, and a list (or description, but list would be more
to-the-point) of conditions the method/class needs.

For example, lately I've been fooling around with the mapping
configuration classes, to "manually" configure nhibernate (and fill
mappings from code, sort-of-fluentnh), and it took me quite a while to
figure out what was necessary.

For example (pseudo-names..):

method Mapping.AddPersistentClass(PersistentClass) adds a given
PersistentClass definition to the mappings.
Needs:
+ valid PersistentClass.Table.
+ EntityName
etc..

I know this mapping area might be considered internal to nhibernate,
but this same remark applies to other areas of NHibernate..

Just my 2 cents..

Regards,
Matthijs ter Woord

> --
> You received this message because you are subscribed to the Google Groups
> "nhusers" group.
> To post to this group, send email to nhu...@googlegroups.com.
> To unsubscribe from this group, send email to
> nhusers+u...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/nhusers?hl=en.
>
>

[Mikael Henriksson]

It would be wonderful to have a real life enterprise application
throughout the documentation which could be downloadable as well.
The NHibernate 3.0 cook book had some very good and often overlooked
samples.

Cheers

[John Davidson]

The current documentation does not include images, following the standards set for GPL'd OSS projects. As this is a non-GPL'd project could we allow some images, especially for class diagrams.

I would recommende png as the image format and note that png license is compatible with NHibernate license (even without the inclusion of libpng)

John Davidson

[Petr Kozelek]

I am not sure whether this thread is about collecting ideas for XML
docs or some kind of extended docs - maybe on NHforge.
I miss deeper documentation how to extend NHibernate. How to hook
entity lifecycle (via implementing interface, via configuration).
Additionaly, the extended documentation should contain pros and cons
of both the aproaches.

The same goes for ConfOrm. It is a completely new approach. In spite
of that I can use it for mapping quite complex relations I still am
not very clear about the whole idea of it. Documentation for it should
contain a real word example with explanations of intentions that lead
the development team to such an architecture of ConfOrm.

[Matteo Migliore]

I think that bibliography like in our HSDK project (http://
hyperionsdk.codeplex.com) could be useful
to understand why a problem is solved in a certain way.

Also a solution with multiple projects and tests (to explain use
cases) could be very useful.

Every "How To" that you propose could be related to a sample project
in this "all in one solution"
organized using "a lot" of solution folders :), to divide arguments.

My 2 cents.

--
Matteo Migliore

Blog http://blogs.ugidotnet.org/matteomigliore
Twitter http://twitter.com/matteomigliore
CodePlex http://hyperionsdk.codeplex.com

[Matteo Migliore]

> Consider this thread as a poll to know what you would like to have in our
> reference documentation.
> We know that we have some obsolete info, some incomplete info and a lot of
> info spanned in various blog posts.
>
> What you would like to have in our reference documentation ?

I think that a solution that contains projects to explain use cases
would be a good starting
point. Simple projects divided by argument and tests could be a way.

I think also that the "bibliography" used by the team to project
features, solve issues and
apply a certain pattern could be useful, we do that in our project
HSDK (http://hypersionsdk.codeplex.com),
so users can walk along the road you've done and understand better why
"something" is implemented
in a way instead another.

My 2 cents.

[Fabio Maulo]

This is about NH.
ConfORM is another stuff.

--
Fabio Maulo

[Thiago Alves]

Mikael,

I strongly agree with your comment and I am willing to contribute to such project. We need a sample application which is small in scope but complex enough to demonstrate the most used NHibernate features as well as some business logic, unit tests, and so on.

Best Regards,

Thiago

[Francois Ward]

What I would add personally, in order of importance:

-Make sure all of the mapping properties are documented. Some just have 1 liners which makes it hard to know their purpose, never mind how to use them.

-Reference for HQL. Right now its mostly the Hibernate HQL doc nearly copy pasted. I keep finding stuff you can do in HQL i didn't know about by googling around :) 

-XML comments/docs on all the methods for intellisense.

-Reference for what constructs of criteria/linq/hql generates in various scenarios for the more common dialects, a little like what Ayende does on his blog. I realize that one would take way too much work to write up, but i can dream :)

-Francois

On Mon, Oct 25, 2010 at 8:35 AM, Fabio Maulo <fabio...@gmail.com> wrote:

[Mario Dal Lago]

include the new features of nh3 , Query, QueryOver, etc. Mario Dal Lago --- El lun 25-oct-10, Fabio Maulo <fabio...@gmail.com> escribió:

[Anne Epstein]

This isn't exactly a feature of the new documentation, but any chance of keeping up a copy of the documentation as of NHibernate 2.1 on NHForge for a few months with a clear link to the 2.1 documentation from the top of the 3.0 version, and very clearly, very obviously marking the version number on both?  Of course, NH 2.1 is no longer supported, but it will take a while to for people to get their projects updated to the new version of NHibernate, and once the single linked version of the documentation gets bumped, it gets a tougher to find documentation that is accurate for the prior version ("why isn't this QueryOver feature working? it's not supported in 2.1? oh, I should have noticed that tiny 3.0 at the top... oops. so where's the 2.1 docs then?")..   I suppose making it harder to find 2.1 documentation is encouragement to move to 3.0, but there are probably more user-friendly forms of encouragement, and keeping up an older version wouldn't require much upfront or ongoing work.  Yes, there is version-specific documentation bundled in the source, but that's probably not the go-to location for reference documentation that most people are using.

[Fabio Maulo]

Don't forget that we are deploying binaries, API doc, reference doc, and sources with each final version

http://sourceforge.net/projects/nhibernate/files/

Reference are available in pdf, chm, htmls and single html.

API in chm format compiled with SandCastle..

Fabio Maulo

[Ghidello]

What I think will be really usefull is a "live" list of bad practices
and habits using NH. I saw many people (Yes, I'm talking about me
hiding myself between my imaginary friends.. :D ) getting involved
into NH without having a real understanding of the environment. I saw
the same people googling for solving a specific problem and coming up
with quick and dirty solution "thast simply works". Finally I saw
people saying "Ups" and "Doh" more and more often when, finally, they
found the time to start studying seriously NH and they realized the
number of mistakes they made.

This is the reason why I'm talking about a live page of bad habits:
people is very productive when talking about weird solutions! :) A
good list of things to avoid would drive their google search to a
better solution until they'll have the time to understand the right
way by theirself.

Thanks in advance from the "people"!

Alessandro

On Oct 25, 2:35 pm, Fabio Maulo <fabioma...@gmail.com> wrote:

[sbohlen]

I would second that --a sort of "Patterns and Anti-Patterns" for
common use-cases sounds like a good suggestion to me.

Though we'd need to ensure that the 'Patterns" part doesn't end up
sounding exactly like the NHibernate Cookbook :D

-Steve B.

[Angel Java Lopez]

Hi people!

I agree with Francois.

One point: write a demo application, in general, DOES NOT cover all the mapping properties, HQL, etc... I prefer the way PHP documentation is organized: every function, has one or more mini example. There is NO demo app for PHP: too much points to be covered by such kind of application.

Examples:
http://www.php.net/manual/en/language.oop5.properties.php
http://www.php.net/manual/en/function.mail.php

Note the help of programmers comment in that pages. The most relevant are incorporated to documenation.

I prefer the effort is directed to:

- "Doc coverage" of every (or main) feature
- "Example coverage" of every (or main) feature

As an example: I didn't read the current NH doc, but years ago, I was trouble understanding "inverse=" behavior and necessity, without a clear and dedicated example. (hmmm.. maybe, the trouble was with Hibernate doc).

I guess a group of dedicated devs/users (I could help) could attack this "doc/example" coverage.

Angel "Java" Lopez
http://www.ajlopez.com
http://twitter.com/ajlopez

[Fabio Maulo]

Ale,

can you recall which was the list of "bad practices" ?

--
You received this message because you are subscribed to the Google Groups "nhusers" group.
To post to this group, send email to nhu...@googlegroups.com.
To unsubscribe from this group, send email to nhusers+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/nhusers?hl=en.

--
Fabio Maulo

[Jason Dentler]

This is all good feedback. Just one note: The reference docs are part of a build process. Unless Fabio & the team have other plans, we'll only be changing the content.

@Steve B- "doesn't end up sounding exactly like the NHibernate Cookbook"... not likely. Especially when you do the voices correctly. 

[Alessandro Ghidini]

Hi Fabio,

I'll have to think a bit (my list can be unfortunately long) but the first I can remember are: 

1) disabling the lazy loading behaviour instead of using the right fetch mode

2) not using a transaction when "just" selecting data

3) not using the futures when sending more than one query

4) not putting upper and lower bounds when selecting the data (read the last 2 also as not performing a good pagination query)

5) I know that this is not directly related to NH, but think to a web service call which is set to return an object coming from a query: during the serialization of the response NH will be asked to resolve every property contained into the object (which the user may not be interested in). So the bad habit here could be to expose the NH related entity instead of a DTO or something like that. Webservices are another reason for disabling the lazyload cause they do not like to serialize the proxies

6) An example similar to the previous is when you load (with an objectdatasource) an entity which contains multiple related objects and bind it to a control who shows the properties of the contained objects making NH perform a number of additional queries

7) You don't have only the Criteria way of performing queries.. HQL is much more simple to use in many cases

I know that I should rewrite this list in an understandable english but I hope that you'll get the point :)

Ciao e grazie

Ale

Alessandro Ghidini

[Fabio Maulo]

someone of your point sound like this serie:

http://fabiomaulo.blogspot.com/2009/05/empezando-con-nh-mappings.html

[Alessandro Ghidini]

Mi espanol no esta bueno para nada pero securo que voy a estudiar tu posts! :)

I just started reading it but yes it looks like what I was thinking to.