The NH docs are actually pretty damn good, sure there are some holes for the more complex features, but it's still considerably better than the majority of OSS projects out there. New users tend to have the initial problem of actually finding the central location, but once they're there I think it's pretty solid. One issue is that people are still going to the wrong locations for documentation. We (hopefully) all know NHForge is the "hub", yet I'm still seeing high profile bloggers linking to nhibernate.org. This should be corrected.
As for the documentation itself, there does need to be some coverage of the more advanced features. As a developer of FNH I find myself reading the xml schema a lot to find out exactly what is available, there should at least be some intermediary that isn't as obtuse as actually reading xml, but may not necessarily go into the depth that the main NH docs do. Anyone follow? :) A lot of my time is spent on other things, but if we can decide on how and where all this should happen I'd gladly document as I go while I'm digging in the XSD. On Mon, May 18, 2009 at 12:30 PM, 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 > > > --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
