http://ofbiz.116.s1.nabble.com/Users-Updated-documentation-tp138178p138188.html
> Hi
>
> I like the way the mysql documentation works, people can add comments, tips,
> etc. at the bottom of each page and then every now and again someone could
> come along and integrate the useful comments into the page itself (people
> could possibly even vote for comments that they found useful). That way
> people can easily add things without having to worry about formatting and
> grammar, and then an editor can oversee the growth of the formal docs.
>
> Regards
> Scott
>
> -----Original Message-----
> From:
[hidden email] [mailto:
[hidden email]]
> On Behalf Of Adrian Crum
> Sent: Thursday, 30 March 2006 7:05 a.m.
> To: OFBiz Users / Usage Discussion
> Subject: Re: [OFBiz] Users - Updated documentation ...
>
> I tried contributing to the Wiki, but my contributions would get deleted
> everytime someone took it upon themselves to "groom" or "garden" the Wiki
> site.
>
> I haven't been invited to contribute to the "For Sale" documentation, so I
> have
> no experience with that.
>
> It would be nice to have a system where the community can easily contribute
> to
> the documentation, but not be as "loose" as the Wiki. Maybe more along the
> lines
> of the Jira site - where contributors can freely and easily contribute
> documentation, but it doesn't become an official part of the project until
> someone reviews it and includes it.
>
> So, that would be my recommendation: set up a site like the Jira (for
> documentation only) and have someone like your technical writer review the
> submissions and include them in the final "product."
>
>
> David E. Jones wrote:
>
> > This does bring up an interesting discussion point: how should we manage
> end-user oriented documentation (and other documentation too...)?
> >
> > Notice that I did _not_ ask what would everyone like to see in the
> documentation... that is a moot point without a way to go about getting it
> in place. I'd rather not talk about that as it has been discussed quite a
> bit, it confuses the point of how to get things done and who will do them,
> and often leads to blaming those who have contributed to OFBiz for not
> contributing even more.
> >
> > The eventual form of the documentation is another problem, made more
> difficult by the fact that depending on how you look at it there are either
> many targets or one moving target to go after...
> >
> > The Undersun documentation site is something Andy and I started pushing a
> while back and is built (mostly by Al Byers) on the OFBiz content component.
> The actual content (images and text) are maintained and mostly written by
> Les who is a technical writer we are contracting with to maintain it.
> >
> > This is commercial rather than collaborative in nature because
> collaborative attempts in the past at OFBiz documentation have failed so
> completely that nothing has been written except isolated pockets of
> documentation (including the "official" documentation on the ofbiz.org site)
> that we not only don't get many (or any) contributions, but we almost never
> even get feedback on the documentation.
> >
> > I think this is largely by the nature of documentation. When most people
> say they want "documentation" what they really want is understanding of the
> software either technical or business and end user level. The hope of
> documentation is to get people to those points of understanding as quickly
> as possible, but initially even seeing the size of the documentation and the
> options available can be a serious "gumption trap". For a great discussion
> on gumption traps I recommend the book "Zen and the Art of Motorcycle
> Maintenance" by Robert Pirsig.
> >
> > Anyway, back the real issue...
> >
> > My hope with the Undersun site is that it would become more collaborative.
> Those who are interested in contributing have been given free accounts to
> the site. We have a nearly full-time technical writer on contract to help
> maintain the information so that it can hopefully remain more consistent and
> better controlled.
> >
> > If people object to the commercial nature of it, ie we charge for access
> to the site on a subscription basis, then that's fine. If there are other
> alternative it would be great. So far the site is not profitable, not even
> close to profitable. In fact, Andy and I subsidize the site pretty heavily
> in hopes that someday it will pay for itself, and in the mean time we
> believe it is important to the success of OFBiz to have end-user oriented
> documentation, and so we continue to invest what little we can in it.
> >
> > I would appreciate any feedback anyone might have. In general it would
> also be great to see more invested in this and other documentation efforts
> as it is one of a few areas of OFBiz that could use some work.
> >
> > -David
> >
> >
> >
> > Ian Gilbert wrote:
> >
> >>Hi All,
> >>
> >>I'm glad they are popular :) I am happy to release these under any
> license but I'm not sure that
> >>this will have the desired effect. My reasoning is that the development
> community (that this doc
> >>is not really targeted at) has a range of resources to pull information
> from (wiki, production
> >>guide, mailing lists, intro docs on the Open Source Strategies site, the
> Undersun Consulting docs
> >>etc.,) but most of my users are non tech and would simply get lost in the
> information. Indeed
> >>they would not even consider contributing back and probably would have
> difficulties understanding
> >>the concept. Certainly there would be hurdles to stop them (I cannot see
> them using Jira for
> >>example although I can see them deluging me with the same emails a few
> hundred times). There is
> >>not too much user orientated resource available at the moment but this is
> understandable because
> >>the type of business user who has got involved in the project so far have
> all had a considerable
> >>technical ability and inclination.
> >>
> >>We have quite a high turnover of people at ES and so it made a lot of
> sense to write some form of
> >>training or user reference doc simply to reduce the amount of time that I
> was spending with people
> >>on the same questions. I think that there is still lots to do on this
> (similar books run to 5-600
> >>pages in the shops so I'm not going to stop now ;) Granted I've skipped
> the traditional
> >>'Introduction to the Internet' which most of them have (don't worry guys -
> it will be in the next
> >>version) but even so there is a huge amount still to cover even with the
> limited way in which we
> >>use Ofbiz. I was also keen to create a doc that could be pulled apart and
> used as a test script
> >>as much of the UAT we do is much easier that way.
> >>
> >>The reason I don't think it will work in the community in the same way is
> that there are very few
> >>end users (or appear to be) on the list that wouldn't be better off
> updating the wiki. I've used
> >>Open Office to create the DocBook format (it was the first of these that
> I've done and I do like
> >>it but would like to use another editor to create new tags which I think
> might end up with a more
> >>flexible document (i.e. use one document root to create sub docs for
> Administrators, store clerks,
> >>accounts team etc., which should be quite straightforward with xml) but I
> have to fit this into
> >>gaps between contracts like the one I've got right now.
> >>
> >>That said I'm happy for this to be released under any license and for
> anyone to use this in any
> >>way they see fit. Considering the value that ES and I have had from
> participating in this project
> >>it really is the least I can do. At some point I would like to write a
> more professional guide
> >>and ideally have it published properly. I think that this would be better
> created with a number
> >>of authors simply because the subject is so big.
> >>
> >>Very best wishes
> >>
> >>Ian
> >>
> >>
> >>
> >>
> >>On Wed, March 29, 2006 12:28, David Welton wrote:
> >>
> >>>>>Yes, nice job indeed. It would be good to see something like this
> >>>>>distributed with OFBiz itself.
> >>>>
> >>>>Yes, or maybe a link from official OFBiz site (Doc tab) will be
> sufficient ?
> >>>>
> >>>
> >>>As the years go by, stuff that doesn't get held together tends to
> >>>float apart (bit rot). Perhaps if the DocBook sources were in
> Subversion, more people would update
> >>>them and add to them, as well. However, this is a decision for Ian, who
> would have to release the
> >>>docs under a suitable license, and the developers, who would have to
> choose to include it.
> >>>
> >>>--
> >>>David N. Welton
> >>>-
http://www.dedasys.com/davidw/> >>>
> >>>
> >>>Linux, Open Source Consulting
> >>>-
http://www.dedasys.com/> >>>
> >>>
> >>>_______________________________________________
> >>>Users mailing list
> >>>
[hidden email]
> >>>
http://lists.ofbiz.org/mailman/listinfo/users> >>>
> >>>
> >>
> >>
> >
> > _______________________________________________
> > Users mailing list
> >
[hidden email]
> >
http://lists.ofbiz.org/mailman/listinfo/users> >
>
> _______________________________________________
> Users mailing list
>
[hidden email]
>
http://lists.ofbiz.org/mailman/listinfo/users>
>
> _______________________________________________
> Users mailing list
>
[hidden email]
>
http://lists.ofbiz.org/mailman/listinfo/users