Posted by
Scott Gray on
Mar 30, 2006; 10:08am
URL: http://ofbiz.116.s1.nabble.com/Users-Updated-documentation-tp138178p138187.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.
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users
_______________________________________________
Users mailing list
[hidden email]
http://lists.ofbiz.org/mailman/listinfo/users