I agree with the assessments noted here.  It's not bad documentation,
but finding it (especially finding what is relevent to which version)
is a daunting task for a new NHibernate user.  I started down the
NHibernate path about 3 or 4 times before actually getting to the
point of being able to implement into a project.  I would just run out
of time to dig through the myriad of disjointed information.  The
nhforge site is a step in the right direction I believe and would be
willing to help as I can.

I can tell you that I got excited about NH when things started to
click and I was able to find the documentation for a problem, but when
you reach a roadblock and can't find the answer it turns you off of
the tool quickly.  The larger the user base, the larger the pool of
developers for potential contributors to the project.

Also, thank you to the contributors/creators.

On May 18, 6:25 pm, Stefan Steinegger <[email protected]> wrote:
> @Fabio, I already wrote you a mail with some questions about where and
> how to write the documentation. I think it is very important.
>
> @Humberto: That's exactly what I mean. The documentation is mentioning
> many features and one can not understand what it is good for.
> Sometimes I struggled to find a solution in some blog about my
> problem, and found it afterwards in the reference documentation. But
> when I read it the first time, I didn't understand that it is a
> solution for my problem.
>
> Sometimes I answer questions on stackoverflow.com. There are many
> questions about basic stuff, mostly components and lists, that should
> be clear in the docs.
>
> I think, for OSS NH is not so badly documented. But documentation is a
> part of the quality. A good documentation enhances the quality of the
> product directly and attracts more people to use it.
>
> On 18 Mai, 18:56, Fabio Maulo <[email protected]> wrote:
>
>
>
> > The doc available with sources is using DocBookhttp://www.docbook.org/
>
> > To have a WYSIWYG version a conversion to the last DocBook format is needed
> > and, after that, you can use oXyGen (http://www.oxygenxml.com/).
>
> > If somebody know a better way to have all things working....
>
> > Probably the wiki is not the better place where put a documentation but, you
> > know, so far was the only way we found to give you the opportunity to
> > collaborate.
>
> > Note: The Knol with NH doc. was created, under users request, before
> > NH-Forge creation.
>
> > 2009/5/18 Humberto Marchezi <[email protected]>
>
> > > 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
>
> > --
> > Fabio Maulo- Hide quoted text -
>
> - Show quoted text -

--~--~---------~--~----~------------~-------~--~----~
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