Documentation of a not-so-trivial tool like NHibernate is definitely an
important issue.
Provided of good documentation NH can become even more popular.

I think there are some gaps to be filled such as:

- More detailed explanation about collections. There are sets, maps, lists
and bags but what are their purposes ? What .NET interfaces are compatible
to each of these collections ?

- There are some features like joins and components whose purpose should be
explained. I see many programmers (including me) reading about feature
without understanding how it cab be effectvely usesul. Components, for
example, make it possible to have 'Value Objects' from DDD in NHibernate.

- I would suggest each NHibernate feature to have a small example with the
generated SQLs to illustrate its usage and effect. Just like Ayende did:
http://www.infoq.com/news/2009/04/nhibernate-mappings.

- More detailed explanation about session management in the Architecture.
Maybe using a small example of the current best practice with contextual
sessions.

On Mon, May 18, 2009 at 8:30 AM, Stefan Steinegger <[email protected]>wrote:

>
> Thanks, Sidar for your response and willingness to help.
>
> I'm a bit disappointed that nobody else answered to my questions. So I
> ask the other way around:
>
> - Are you quite happy with the NH documentation?
> - Do you find complete documentation about the features, and
> understand how to use it?
>
> If so, I don't thinks it's worth to change how it is.
>
> On 15 Mai, 10:18, Sidar Ok <[email protected]> wrote:
> > Starting from the last:
> >
> > 1 - I would contribute as much as I can.
> >
> > I wholeheartedly agree that we need a structure and empty pages to fill
> in,
> > this way contribution will be made easier as well. If I bump into a
> problem
> > and solve it and feel it is valuable, I'll know I have to go under
> Frequent
> > Problems page, or I am searching the mapping reference and seeing an
> > explanation for an attribute is missing and add it.
> >
> > As well as that, it would be very nice if we had a map that shows which
> of
> > the hibernate documentation-reference apply to NH and which do not, or
> > applies but with a different behavior & implementation.
> >
> > A structure that both helps people to contribute to documentation and
> > readers to find content easily.
> >
> > On Fri, May 15, 2009 at 9:56 AM, Stefan Steinegger <[email protected]
> >wrote:
> >
> >
> >
> >
> >
> > > In a thread with Fabio Maulo (http://groups.google.com.ar/group/
> > > nhusers/browse_thread/thread/256e8a8a9958f939/
> > > a41a81c21a26fb03#a41a81c21a26fb03<
> http://groups.google.com.ar/group/%0Anhusers/browse_thread/thread/256...>)
> > > we went off on a tangent and came
> > > to the documentation problem. Here is a summary:
> >
> > > * many things are hardly documented
> > > * the documentation is there (eg in blogs and forums), but could not
> > > be found (it's like a puzzle)
> > > * Contributers are needed to split up the effort needed
> >
> > > Thats what we have:
> > > * nforge.org has a wiki, but there isn't much documentation except of
> > > a part of the well known reference documentation.
> > > * An knol by Fabio with the complete reference documentation of NH
> > > 2.0. I found out that it is free to be edited for everyone, but I
> > > doubt that anybody else ever contributed to it.
> > > * this google group
> > > * Excellent posts by Ayende on his own blog and on nhforge.org.
> > > * hundreds of blogs from many other people for specific topics.
> >
> > > I would like to have a documentation that is
> > > * somewhat complete and detailed about NH's features, syntax and API
> > > * It must be always clear which version of NH is concerned
> > > * A documentation of a version should not only document the difference
> > > to an older version, it should be complete in it's own.
> > > * As much as possible it should be sequentially structured, like the
> > > reference documentation, unlike blogs.
> >
> > > My question is:
> > > * Should we, as a community, build up a complete documentation?
> > > * How should this be done? It must be managed, structures must be
> > > defined.
> > > * Where should this be done? On nhforge's wiki?
> > > * How do we attract potential contributers?
> > > * Last but not least: would you contribute?
> >
> > --
> > Sidar Ok
> >
> > http://www.sidarok.comhttp://www.twitter.com/sidarok
> >
>


-- 
Humberto C Marchezi
---------------------------------------------------------
Master in Electrical Engineering - Automation
Software Consultant and Developer
at the Town Hall of Vitória

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

Reply via email to