http://ofbiz.116.s1.nabble.com/Users-Updated-documentation-tp138178p138186.html
I haven't been invited to contribute to the "For Sale" documentation, so I have
the documentation, but not be as "loose" as the Wiki. Maybe more along the lines
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>